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Introduction 


This Class Libraries Reference covers the two class libraries that are included 
with Microsofte C/C++. The book is divided into three parts: 


Part 1 Introduction to the Microsoft Foundation Class Library 
Part2 The Microsoft Foundation Class Reference 


Part3 The Microsoft iostream Class Reference 


Part 1 contains overview material for the Windows™ and general-purpose classes 
in the Microsoft Foundation Class Library followed by an alphabetical listing of 
all global functions and macros. In addition, it contains reference chapters for 
Microsoft Foundation Class Library diagnostic services and exception processing. 
The last two chapters consist of a Windows message map cross-reference and a 
listing of structures and enumerated values for Windows. 


Parts 2 and 3 both begin with class hierarchy diagrams for their respective librar- 
ies. These hierarchy diagrams, together with the subset diagrams included with 
each Foundation class, are useful for locating base classes. Be aware that the class 
documentation does not include repeated descriptions of inherited member func- 
tions, inherited operators, and overridden virtual member functions. You must al- 
ways refer to the base classes depicted in the hierarchy diagrams. 


Parts 2 and 3 list classes in alphabetical order. Each class description includes a 
member summary by category followed by alphabetical listings of: 


= Member functions (public, protected, and private intermixed) 

= Overloaded operators 

= Data members 

= Manipulators (iostream classes only) 

Public and protected class members are documented only when they are normally 
used in application programs or derived classes. Occasionally, private members 


are listed because they override a public or protected member in the base class. 
See the class header files for a complete listing of class members. 


In Part 2, please note that the “See Also” sections refer to Windows functions by 
prefacing them with the scope resolution operator (::). For example, ::EqualRect. 


xii The Class Libraries Reference 


More information on these functions can be found in the Windows Programmer’s 
Reference, other Windows references, and Help. 


Note The term “DOS” refers to both the MS-DOSe and IBM Personal Computer 
DOS operating systems. The name of a specific operating system is used when it 
is necessary to note features that are unique to that system. 


Document Conventions 


This book uses the following typographic conventions: 


Example 


STDIO.H 


char, CObject, 
GetTime, TRACE, 
MF_STRING, 
CREATESTRUCT, 
__far 


expression 


[option] 
#pragma pack {1 | 2} 


#Finclude <io.h>, 
MyObject 


CL [loption...]] file... 


Description 


Uppercase letters indicate filenames, segment names, 
registers, and terms used at the operating-system 
command level. 


Bold type indicates C and C++ keywords, operators, 
language-specific characters, and library routines. 
This includes the classes and member functions of the 
Microsoft class libraries, macros, flags, data 
structures and their members, and enumerators. 


Within descriptions of syntax, bold type indicates that 
the text must be entered exactly as shown. 


Many functions and constants begin with either a 
single or a double underscore. These are part of the 
name and are mandatory. 


Words in italics indicate placeholders for information 
you must supply, such as a filename. 


Items inside double square brackets are optional. 


Braces and a vertical bar indicate a choice among two 
or more items. You must choose one of these items 
unless double square brackets ({[ []) surround the 
braces. 


Monospace font is used for examples, user input, 
program output, and error messages in text. It is also 
used for names of user-derived classes and members. 


Three dots (an ellipsis) following an item indicate that 
more items having the same form may appear. 


Example 


while() 
if 


CTRL+ENTER 


“argument” 


"C string" 


Color Graphics 
Adapter (CGA) 


Introduction 


Description 


A column or row of three dots tells you that part of an 
example program has been intentionally omitted. 


Small capital letters are used to indicate the names of 
keys on the keyboard. When you see a plus sign (+) 
between two key names, you should hold down the 
first key while pressing the second. 


The carriage-return key, sometimes marked as a bent 
arrow on the keyboard, is called ENTER. 


Quotation marks enclose a new term the first time it is 
defined in text. 


Some C constructs, such as strings, require quotation 
marks. Quotation marks required by the language 
have the form " " and ' ' rather than “” and’’. 


The first time an acronym is used, it is usually spelled 
out. 


xiii 


Windows Development with the 
Microsoft Foundation Classes 


This chapter categorizes and describes the classes within the Microsoft Foundation 
Class Library that specifically support application development for Microsoft 
Windows, version 3.x. 


1.1 Class Summary 


The following is a list, in functional order, of the Windows-oriented classes in the 
Microsoft Foundation Class Library. 


Note All classes listed below, except CPoint, CRect, and CSize, are directly or 
indirectly derived from the CObject class described in Chapter 2. 


Main Application Class 


CWinApp is the class that encapsulates the code for the initialization, running, 
and termination of the application. 


Window Classes 


The Microsoft Foundation window classes are the key building blocks in a Win- 
dows application. These classes have member functions for processing Windows 
notification messages as well as messages from other classes. Some member func- 
tions communicate directly with Windows itself. An active C++ window object 
contains a Windows HWND. 


You will usually derive classes from the frame and child base classes. You can use 
most of the other window classes directly. 
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Base Class 
CWnd 


Frame and Child Windows 


CFrameWnd 
CMDIFrameWnd 


CMDIChildWnd 


Dialog Windows 
CDialog 
CModalDialog 


Control Windows 
CButton 
CComboBox 
CEdit 

CListBox 
CScrollBar 
CStatic 


Graphics Device Interface (GDI) Classes 


The base class for all windows. 


The main window base class for the single docu- 
ment interface (SDI) frame window. 


The base class for the multiple document interface 
(MDI) frame window. 


The base class for MDI child windows. 


The base class for modeless dialog windows. 


The base class for modal dialog windows. 


Button control windows. 
Combo-box control windows. 
Edit control windows. 
List-box control windows. 
Scroll-bar control windows. 


Static control windows. 


The following classes wrap the Windows device context and drawing tools. They 
allow the developer to take maximum advantage of C++ syntax. 


Device Contexts 
CDC 


CClientDC 
CMetaFileDC 
CPaintDC 


CWindowDC 


The base class for device contexts, used directly 
for whole-display and nondisplay contexts. 


Display contexts for client areas of windows. 
Metafile device contexts. 


Display contexts used in OnPaint member 
functions. 


Display contexts for entire windows. 
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GDI Drawing Objects 
CGdiObject The base class for GDI drawing tools. 
CBitmap GDI physical bitmaps. 
CBrush GDI physical brushes. 
CFont GDI physical fonts. 
CPalette GDI physical palettes. 
CPen GDI physical pens. 
CRgn GDI physical regions. 
Other Classes 
CMenu Menu structures. 
CPoint Coordinate (x, y) pairs. 
CRect Rectangular areas. 
CSize Relative positions or coordinate pairs. 


Windows Global Functions and Macros 


Chapters 3 through 7 of this manual document the elements of the Microsoft Foun- 
dation Class Library that are not directly related to individual classes. A complete 
summary of macros and global functions, including those for Windows, is pro- 
vided in Chapter 3. A message-map reference is given in Chapter 6, and Chapter 7 
lists Windows structures and enumerated values. 


1.2 General Class Design Philosophy 


Microsoft Windows was designed long before the C++ language became popular. 
Because thousands of applications use the C-language Windows application pro- 
gramming interface (API), that interface will be maintained for the foreseeable 
future. Any C++ Windows interface must therefore be built on top of the proce- 
dural C-language API. This guarantees that C++ applications will be able to coex- 
ist with C applications. 


The Microsoft Foundation Class Library is truly an object-oriented interface to 
Windows that has met the following design goals: 


= Execution speed comparable to that of the C-language API 
= Minimum code size overhead 


= The ability to call any Windows C function directly 
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= Easy conversion of existing C applications to C++ 


= The ability to leverage from the existing base of C-language Windows program- 
ming experience | 


= True Windows API for C++ that effectively uses C++ language features 


= Solid foundation for future extensions 


The single characteristic that sets the Microsoft Foundation classes for Windows 
apart from other Windows class libraries is their direct access to the C-language 
Windows API. This direct access does not, however, imply that the classes are a 
replacement for that API. Developers must still make direct calls to some 
Windows functions, GetSystemMetrics, for example. A Windows function is 
wrapped by a class member function only if there is a clear advantage to doing so. 


Because you often need to make native Windows function calls, you should have 
access to the C-language Windows API documentation. This is included with 
Microsoft C/C++ as Help. If you require printed documentation, refer to the 
Microsoft Windows Programmer’s Reference and the Microsoft Windows Guide to 
Programming from Microsoft Press. Another useful book is Programming 
Windows by Charles Petzold, also from Microsoft Press. Many of that book’s ex- 
amples can be easily converted to the Microsoft Foundation Windows classes. 


1.3 C++ and Windows 


Many C++ language features are particularly suited to Microsoft Windows. The 
Windows-oriented classes in the Microsoft Foundation Class Library make 
Windows programming truly systematic. It’s significantly easier to learn Windows 
through a C++ interface than through the standard C interface. 


Message-Based Programming 


Windows is a message-based environment. In the familiar MS-DOS programming 
world, your program calls the operating system. In Windows, the operating system 
(Windows) sends a message to your program. The “program” is associated with a 
particular window, and the message might be “destroy yourself,” “repaint your- 
self,” “your child button was pushed,” or something similar. 


Your program might also send a message to Windows. These “outbound” mes- 
Sages are often directed at a child window, such as a button, list box, or edit con- 
trol, that has inaccessible code. If, for example, you send a “scroll” message to an 
edit control, Windows itself does the work. Your application program cannot inter- 
cept these outbound messages once they are sent. 
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The C++ language naturally accommodates the messaging behavior of Windows. 
Objects receive messages through the “member functions” of their class, and they 
send messages by calling a member function for another object. A C++ object 
represents a Windows window, and the member functions of the class process in- 
dividual messages. The OnPaint member function of a derived window class, for 
example, receives and processes a Windows WM_PAINT message. The 
CListBox member function AddString sends an LB_ADDSTRING message to 
Windows. 


The real magic of the Windows Foundation classes begins here. There is no longer 
any “program logic flow” as in conventional procedural programming. Each win- 
dow object is self-sufficient and is responsible for (1) acting on the messages that 
are important to it and (2) sending messages to other window objects. It can create 
and delete other windows along the way. The interaction among window objects, 
and thus the flow of the program, is governed by the actions of the end user rather 
than by complex code and data structures. 
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Class Derivation 


Polymorphism 


Programmers often try to exploit existing code to solve new problems. In the C 
programming environment, the programmer can “clone” useful code by copying 
it and making modifications. In the C++ programming environment, you add 
functionality through “class derivation”. The functionality of the base class re- 
mains unmodified, but that of the derived class may be added to or changed. 
Derivation works well with Windows because you can extend useful window base 
classes with new member functions and new data members. 


Suppose a frame window base class includes a caption, menu bar, scroll bars, and 
so forth. Also suppose that this base window has the ability to get the input focus 
in response to activation by the mouse. If you need to add the capability of display- 
ing a dialog box in response to an access Key, then you can derive a new class 
from the frame window base class. You get all the base class functionality without 
having to modify its code or worry about its internals. 


There are three or more levels of window class derivation in a typical application 
built with the Microsoft Foundation classes for Windows. CWnd, the base class 
for all windows, contains many member functions that apply to all window 
types. Some second-level derived window classes, such as CFrameWnd, 
CMDIFrameWnd, and CMDIChildWnd, are designed for further derivation. 
Others, such as CDialog, can be used directly or as a base for further derivation. 
Finally, the classes that you derive for your own windows provide the third level 
of derivation. 


Note The CWnd class is useful as a base class for SDI child windows. You do not 
need to derive from one of the second-level classes listed above. 


In the C-language Windows API, the programming interface of a dialog box is 
different from that of a frame window, even though both are defined as windows 
and identified by an HWND parameter. The Microsoft Foundation classes make 
all window types look similar because all are derived from the CWnd base class. 
Microsoft Foundation window classes are truly polymorphic because they give a 
common programming interface to dissimilar window types. 


Reduced Programming “Surface Area” 


C programming with Windows is intimidating because of the complex interrela- 
tionship between functions and the proliteration of messages. The progammer 
must write a WndProc function for each type of window and a main program 
called WinMain. Each WndProc function processes the window’s messages by 
means of a case statement and must be linked to windows and to the application 
through an elaborate data structure. 
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The Microsoft Foundation classes for Windows encapsulate most of this complex- 
ity while allowing the same flexibility found in the C programming environment. 
You don’t need to write the WinMain and WndProc functions because they are 
provided for you. However, you can override them if necessary. 


1.4 Windows Class Categories 


Like any C++ class library, the Microsoft Foundation Class Library encapsulates 
its functionality in classes. The important Windows class categories are: 

= The main application class, CWinApp 

= The window classes—CWnd and its derived classes 


= The graphics device interface (GDI) classes, which support device contexts and 
drawing tools 


= The miscellaneous classes, which support menus, points, and rectangles 


The Main Application Class, CWinApp 


The main application class encapsulates the initialization, running, and termination 
of a Windows application. A Microsoft Foundation Class Library Windows appli- 
cation must contain one (and only one) object of a class derived from CWinApp. 
This class has several important member functions that you can override: 


= InitInstance 


Windows allows you to run more than one copy, or “instance,” of the same ap- 
plication. InitInstance is called every time a new instance of the program 
starts. It must be overridden in order to create a main window and thus start the 
application. It is the most important member function of the class. 


# InitApplication 


This function is called when the first instance of a program starts. The default 
version does nothing, but you can override it if you need special processing for 
the first instance only. 


= ExitInstance 


This function is called each time an application instance terminates, usually as a 
result of the user quitting the application. You can override ExitInstance if you 
need special cleanup processing, such as closing of disk files or deallocating 
memory used during program execution. 


= Onlildle 


The default version of OnIdle does nothing, but your overridden function can 
perform background tasks when no messages are being processed. 
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For a typical Windows application, you need only override InitInstance in a class 
derived from CWinApp. Then you construct a static object of the CWinApp- 
derived class. 
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The Window Classes— CWnd and Its Derived Classes 


You will normally override the InitInstance member function of the CWinApp 
class to create your application’s main window, an object of a class derived from 
CWhnd. This window class, together with all the other window classes, have mem- 
ber functions for receiving and sending messages. 


There are different types of Windows messages. Each type is handled somewhat 
differently by the Microsoft Foundation classes. 


Notification Messages and the Message Map 


A “notification message” is a message sent to a window by Windows itself in re- 
sponse to a keystroke, mouse click, window move, control window activity, or 
other event. If necessary, your application can force Windows to send a notifica- 
tion message. The Microsoft Foundation Class Library has a special mechanism, 
called a “message map,” that links Windows notification messages with the mem- 
ber functions you have written. 


A message map is a table that you include with your window class code. It con- 
tains an entry for each Windows notification message that you intend to process 
with a custom-written member function. The result is a message-processing sys- 
tem that provides all the advantages of virtual functions without the storage 
overhead. 


Many of the member functions that process notification messages are predefined. 
For example, if your class needs to process the Windows WM_CREATE mes- 
sage, you must put the following entry in the class’s message map: 


ON _WM_CREATE() 


and you must declare and implement this exact member function: 


afx_msg int OnCreate( LPCREATESTRUCT Ipcs ); 


Note The afx_msg keyword denotes a notification message declaration or im- 
plementation. It is defined as a no-operation in AFX WIN.H and thus documents 
the fact that the function behaves like a CWnd virtual function. It must be empha- 
sized that message maps depend solely on standard preprocessor macros and not 
on any extensions to the C++ language. 


A table that shows all permitted message-map entries and the corresponding 
member function prototypes is presented in Chapter 6, “Message Map Cross- 
Reference.” For a complete example of message-map usage, see Chapter 6 of the 
Class Libraries User’s Guide. 
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Other notification messages allow you to define your own functions. For example, 
if you need to call a function in response to a mouse click on a button whose ID 
number is IDD_BUTN1, your message-map entry is: 


ON_BN_CLICKED( IDD_BUTN1, OnTopButton ) 


and your member function declaration looks like this: 


afx_msg void OnTopButton(); 


When you define a message map, you specify the base class in addition to the mes- 
sages. This allows the base class to handle messages not handled in the derived 
classes. 


Windows Control Messages 


A Windows control, such as an edit window or list box, is represented by a win- 
dow object (of a class derived from CWnd), but the processing is controlled by 
Windows rather than by the Microsoft Foundation classes. If you need to update a 
control, your application must send a “control message” to Windows. A frame 
window object, for example, can send an LB_ADDSTRING message to a list- 
box window that is its child. The Microsoft Foundation classes wrap this message 
in the CListBox member function AddString. The call looks like this: 


CListBox* listBoxl; // Object initialized elsewhere 
1istBoxl->AddString( "list-box line item" ); 


In this case the phrase list-box line item is sent directly to Windows for dis- 
play. The CListBox member functions cannot access the list-box line items unless 
they retrieve them directly from Windows. 


Other Windows Messages 


Other Windows messages do not relate to controls. If, for example, you want to 
select a font for future text drawing, you must send the WM_SETFONT message 
to the appropriate window. The Microsoft Foundation classes wrap messages like 
this with CWnd member functions. In this example, you call the SetFont member 
function. 


Windows Development 15 


rH Window Objects and the Windows They Represer t ole aay 
A C++ window object i is distinct from its corresponding A indows window ne 
but the two are tightly linked. A good understanding of this relationship is 


3 crucial for effective Microsoft Foundation class penprannies, 


; < "he wi ndow abject is an instance of the C++ CWnd class (or ad oe 
class). It comes and goes in response to your program’s constructor and 
destructor a ue ieee window, on ate other hand, is San ‘internal - 


: ce when the qo object is ead. bat the: window i may b be dest 
by either a LPI ane call ¢ or ae a user’ 8 action. : | 
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Some messages are not wrapped by individual member functions. Suppose you 
derive a class from CWnd and you need a member function that activates the win- 
dow’s nonclient area. The following call accomplishes the task: 


SendMessage( WM NCACTIVATE, TRUE, @ ); 


SendMessage is a CWnd member function, and thus it communicates directly 
with your C++ window object that underlies the Windows window. The 

Send Message function sends its message immediately. Another function, 
PostMessage, posts the message to the Windows message queue for delayed 
processing. 


Direct Calls to Windows 


In many cases your program interacts with Windows through a direct call rather 
than through a sent message. Many of these direct calls are mapped to CWnd 
member functions. If you need to set a window’s caption, for example, you simply 
call CWnd::SetWindowText. 


Control Window Classes 


The Microsoft Foundation Class Library includes classes for standard Windows 
controls, which are actually special-purpose windows. These controls include: 


=" Buttons 

= Combo boxes 
= Edit windows 
= List boxes 

=" Scroll bars 


= Static controls 


You will seldom need to derive from these classes because most of their function- 
ality is determined by Windows itself. If you need a button, for example, you con- 
struct an object and then specify one of several predefined styles to the Create 
member function. 


Buttons, like other controls, are designed to be child windows. When the user 
clicks a button, for example, the button object sends a BN_ CLICKED message to 
its parent window object. The parent window class must define a message map 
and have an appropriate member function to handle the message from the button. 
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Note Do not confuse the scroll-bar control window with the frame window’s built- 
in scroll bars. Any frame window can have horizontal and vertical scroll bars if it 
is created with the proper parameters. The scroll bars created in a frame window 
this way are not actually separate child windows. A true scroll-bar control is a sep- 
arate child window that can be sized and placed as required. 


Dialog Boxes 


A “dialog box” is a special kind of frame window that contains a number of child 
window controls, such as buttons and edit fields. It is generally used to collect data 
from the user. A “modal” dialog forces the user to complete the requested action 
prior to returning to the application’s main window. The “modeless” dialog allows 
the user to continue work in the parent window. 


Dialog boxes are frequently defined, along with the constituent child windows, in 
“resource files” where the child windows have assigned ID numbers. Your pro- 
gram must construct an object of class CDialog or CModalDialog (or a derived 
class) in order to use a resource-based dialog box. If your dialog box requires only 
routine operations, such as detecting button hits and reading input strings from edit 
controls, then you do not have to construct child control window objects; instead, 
you call member functions of the dialog base class that use child window IDs as 
arguments. 


If, for example, you need to read the string from an edit window identified as 
IDM_DATA, then use the CWnd member function GetDlgItemText as follows: 


GetDlgItemText( IDM_DATA, string, 128 ); 


where string is the address of a character buffer and 128 1s the maximum 
buffer size. You do not need to reference an edit window object. 


If you do need to access resource-based dialog child windows as C++ objects, the 
Microsoft Foundation classes provide a way. The GetDigItem dialog class mem- 
ber function returns a CWnd pointer that corresponds to a dialog child window ID 
number that is defined by the resource. This CWnd pointer refers to an internally 
allocated window object that is stored in a temporary table. It allows you to 

use the appropriate window class member functions. The IsKindOf and 
GetRuntimeClass member functions of CObject can help identify the specific 
window class of the object. 


If, for example, you need the line count from the edit control introduced pre- 
viously, then use CWnd::GetDigItemText as follows: 


CEdit* pEdit = (CEdit*)GetDlgItem( IDM_DATA ); 
int count = pEdit->GetLineCount(); 
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Graphics Device Interface (GDI) Classes 


The CWinApp class and the CWnd derivatives are by far the most important 
Windows-oriented classes in the library. Most are intended for derivation. The 
GDI Windows classes are included as a convenience for the C++ programmer. 
Each corresponds almost exactly to a Windows data structure and is generally not 
used for derivation. 


The Device Context Classes 


CDC, CPaintDC, CWindowDC, CClientDC, and CMetaFileDC are “device 
context” classes because they are C++ wrappings of the Windows device context. 
A device context is a Windows data structure associated with a physical device. It 
is the Windows method of rendering graphics in a hardware-independent manner. 
In order to draw or print in a window, you must first get access to a display device 
context object. 


The base class, CDC, can be used directly to access the entire display or a nondis- 
play context. A “nondisplay context” is a hardware device, such as a printer or 
plotter, that has a Windows driver. 


A CWindowDC context is a “display” context that is “clipped” (by Windows) to 
include only the area of its associated window. A CClientDC context includes 
only the window’s “client” area (exclusive of title bar and scroll bars). A 
CPaintDC context is like a CClientDC context except that it is enhanced (by the 
Microsoft Foundation Class Library) to work in an OnPaint member function 
without the need for the BeginPaint and EndPaint function calls. 


The most frequently used device context is CPaintDC. A typical OnPaint mem- 
ber function obtains and uses a device context as shown: 


void CMainWindow: :OnPaint( ) 
{ // BeginPaint function call not required 
CPaintDC dc( this ); // The device context for this window 
dc.TextOut( @, 0, "hello", 5 ); // Top left of the client rectangle 
} // EndPaint function call not required 


The GDI Object Classes 


The Windows GDI employs various drawing tools, including pens, brushes, 
palettes, fonts, bit maps, and regions. Many device context operations, such as 
drawing and painting, depend on a specific drawing tool being linked to the device 
context. In the native Windows environment, this operation is known as “selecting 
a GDI object into a device context.” In the Microsoft Foundation classes, a tool 
type is represented by a class derived from CGdiObject. | 
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The base class of the device context classes, CDC, has a SelectObject member 
function overloaded for each GDI-object-derived class. This function selects a 
GDI object to a device context (and returns the previously selected object of that 
type). Thus you can attach a brush to a paint display context (and use it) as follows: 


// Create a device context for this window 
CPaintDC dc( this ); 

// Construct a crosshatch filling brush 

CBrush brush( HS _DIAGCROSS, @L ); 

// Select the brush into the device context 
CBrush* pOldBrush = dc.SelectObject( &brush ); 
// Paint the ellipse with crosshatching 
dc.Ellipse( @, 20, 40, 60 ); 

// Restore the original brush 

dc.SelectObject( pOldBrush ); 


The last statement disconnects brush from dc at the Windows level. This per- 
mits the Windows brush to be deleted by the CBrush destructor (when the brush 
object goes out of scope). It is very important to delete Windows GDI objects; 
otherwise their memory will not be reclaimed, even after the Windows application 
terminates. Windows GDI objects cannot be deleted as long as they are selected in 
a valid device context. 


Other Windows Classes 


There are several other classes in the Microsoft Foundation Class Library that 
bring C++ syntax to Windows. These classes include CMenu, CPoint, CRect, 
and CSize. 


The CMenu Class 


A Windows menu is a data structure that associates user actions with 
WM_COMMAND messages. The CMenu class wraps this menu structure and 
provides a constructor for an empty menu. A menu’s list of choices can be altered 
dynamically through member functions such as AppendMenu, InsertMenu, and 
DeleteMenu. The LoadMenu member function loads a menu object with a menu 
definition from a resource file. 


You can attach a resource-based menu, identified by a string or resource ID, 
directly to a window (through the frame window’s Create member function) 
without defining a CMenu object. Alternatively, the window SetMenu member 
function associates a CMenu object with the window. 


The WM_COMMAND messages that result from menu activity must be pro- 
cessed by window class member functions that are declared through message- 
map entries. 
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The CPoint, CSize, and CRect Classes 


CPoint and CSize are simple classes that define absolute and relative (x, y) points 
and provide some useful overloaded operators. The CRect class defines rectangu- 
lar regions specified by the (left, top) and (right, bottom) coordinates. CPoint and 
CRect inherit from the Windows POINT and RECT structures. 


Many Microsoft Foundation class functions take POINT structures or pointers to 
RECT structures as parameters. Because CPoint and CRect are derived from 
these structures, the compiler can accept objects in place of structure instances. 


General-Purpose 
Foundation Classes 


This chapter categorizes and describes the general-purpose classes within the 
Microsoft Foundation Class Library. These classes can be used alone in an MS- 
DOS application, or they can be combined with the Microsoft Windows classes 
described in Chapter 1. 


2.1 Class Summary 


The following is a list of the Microsoft Foundation Class Library’s general- 
purpose classes categorized by function. CObject is the root class in the Microsoft 
Foundation class hierarchy. 


File Classes 


CFile Binary disk files. 
CMemfFile In-memory files. 
CStdioFile Buffered stream disk files, usually text mode. 


Object Input and Output 


CArchive Persistent storage for objects. 
CDumpContext Destinations for diagnostic dumps. 
Exceptions 

CException Base class for exceptions. 
CArchiveException Archive exceptions. 
CFileException File-oriented exceptions. 


CMemoryException Out-of-memory exceptions. 
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CNotSupportedException 


CResourceException 


Collections 
CByteArray 
CDWordArray 
CObArray 
CPtrArray 
CStringArray 
CWordArray 
CObList 

CPtrList 
CStringList 
CMapPtrToWord 
CMapPtrToPtr 
CMapStringToOb 


CMapStringToPtr 


CMapStringToString 


CMapWordToOb 
CMapWordToPtr 


Exceptions resulting from the invocation of an 
unsupported feature. 


Exceptions resulting from a failure to load a 
Windows resource (Windows only). 


Arrays of bytes. 

Arrays of double words. 

Arrays of CObject pointers. 

Arrays of void (generic) pointers. 

Arrays of CString objects. 

Arrays of words. 

Lists of CObject pointers. 

Lists of void (generic) pointers. 

Lists of CString objects. 

Maps that associate void pointers to words. 
Maps that associate void pointers to void pointers. 


Maps that associate CString objects to CObject 
pointers. 


Maps that associate CString objects to void 
pointers. 


Maps that associate CString objects to CString 
objects. 


Maps that associate words to CObject pointers. 


Maps that associate words to void pointers. 


Miscellaneous Support Classes 


CString 
CTime 
CTimeSpan 


Character strings. 
Absolute time and date values. 


Relative time and date values. 
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Global Functions and Macros 


Chapters 3 through 6 of this manual document the elements of the Microsoft Foun- 
dation Class Library that are not directly related to individual classes. A complete 
summary of macros and global functions is provided in Chapter 3, while diagnos- 
tic services, including memory diagnostics and object dump functions, are dis- 
cussed in Chapter 4. Exception processing, which uses TRY, CATCH, THROW, 
and other macros, is covered in Chapter 5. 


2.2 CObject Services 


The CObject base class provides the following useful services to objects of its 
derived classes: 


= Object persistence 
= Object diagnostics 
=» Run-time class information 


= Compatibility with selected collection classes 


Some of these services are available only if you use certain macros in derived 
class declarations and implementations. In order to make use of the services listed 
above, you should seriously consider deriving most of your nontrivial classes from 
CObject. Many of the Microsoft Foundation classes are so derived. 


Even though CObject is not a true “abstract” base class, you are advised not to 
construct objects of this class. 


Object Persistence 


Class CObject, in conjunction with class CArchive, supports “object persistence” 
through a process called “serialization.”’ Object persistence allows you to save a 
complex network of objects in a permanent binary form (usually disk storage) that 
persists after those objects are deleted from memory. Later you can load the ob- 
jects from persistent storage and “reconstitute” them in memory. 


Serialization is not random access, but rather sequential. A group of objects is writ- 
ten to an archive, which is associated with an individual CFile object. If the ob- 
jects to be serialized are contained in a collection, then a single Serialize call for 
the collection object results in the serialization of the whole collection, even if it 
contains nested objects or heterogeneous object collections. For a good example of 
collection serialization, see the tutorial in the Class Libraries User’s Guide. 
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When you create your own serializable CObject-derived class, you must use the 
DECLARE_SERIAL macro in the class declaration, and you must use the 
IMPLEMENT_SERIAL macro in the class implementation. If you have added 
new data members in your derived class, you must override the base class 
Serialize member function to store object data to the archive and load object data 
from it. 


Like the iostream classes, CArchive provides insertion (<<) and extraction (>>) 
operators. 


Object Diagnostics 


The Microsoft Foundation classes provide many diagnostic features, but diagnos- 
tic object printing and validity checking are specific services of the CObject class. 
For diagnostic features that are not class oriented, see “Memory Diagnostics” later 
in this chapter, on page 29. 


Diagnostic Dump Context 


The CDumpContext class works in conjunction with the Dump member function 
of the CObject class to provide formatted diagnostic printing of internal object 
data. CDumpContext, like the ostream class (in the iostream library), provides 
an insertion (<<) operator that accepts not only CObject pointers but also standard 
types and CString and CTime objects. 


A predefined CDumpContext object, afxDump, is available in the Debug version 
of the Microsoft Foundation classes (#define _DEBUG is required in your source 
code). With MS-DOS, the output from afxDump goes to stderr. With Windows, 
the output goes to the CodeView® debugger if it is present; otherwise it goes to 
device AUX. 


Without any programming on your part, the Dump member function of the 
CObject class provides a hexadecimal printout of the contents of your derived 
object. If you override the base class Dump member function in your derived 
class, you can get a formatted dump of your object’s contents. If you have used 
the DECLARE_ DYNAMIC or DECLARE_SERIAL macros in your derived 
class declaration and if you have used the IMPLEMENT_DYNAMIC or 
IMPLEMENT_SERIAL macros in your derived class implementation, then 
Dump prints your object’s class name even if you supply a generic CObject 
pointer. 
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Object Validity Checking 


The AssertValid member function of CObject always returns TRUE. If you over- 
ride the base class Assert Valid member function in your derived class, you can 
perform a specific test of your object’s internal consistency. 


Run-Time Class Information 


The C++ language was designed for speed and efficiency; therefore, binding 
among functions and data elements is done at compile and link time. Even the 
implementation of virtual functions depends on a data structure (known as the 
v-table) that is set up during compilation. Other object-oriented languages, such as 
Smalltalk, are designed for flexibility. Their binding is done at run time; objects 
send and receive standard-format messages that are processed by an interpreted 
language. 


The Microsoft Foundation classes offer the developer some optional features usu- 
ally associated with a run-time—bound system. If you derive a class from CObject, 
you can use member functions to access, at run time, (1) the class name and (2) 
the classes above it in the derivation hierarchy. You can also retrieve class infor- 
mation for any CObject-derived class declared in your program. This information 
allows you to safely cast a generic CObject pointer to a derived class pointer. 


Run-time class information is particularly valuable in the Debug environment 
because it can be used (1) to detect incorrect casts and (2) to produce object dumps 
with class names included. | 


Run-time class information is, of course, available in the Release environment. If 
in Windows, for example, you need to process the children of a frame window, 
you can use the frame’s GetWindow member function to return a generic CWnd 
pointer for each child window. If you want to know the child’s specific class, then 
you can use the CObject member functions IsKindOf or GetRuntimeClass. 
During serialization, the runtime class information is stored to the archive along 
with object data. 


Run-time class testing is not meant to be a substitute for using virtual functions. 
Use the run-time type information only when virtual functions are not appropriate, 
as in the GetWindow example described above. 


In order to access run-time type information, you must use the 
DECLARE_DYNAMIC or DECLARE_SERIAL macros in your class 
declaration, and you must use the IMPLEMENT_DYNAMIC or 
IMPLEMENT_SERIAL macros in your class implementation. 
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Compatibility with Selected Collection Classes 


The collection classes CObArray, CObList, CMapStringToOb, and 
CMapWordToOb accept CObject pointer elements and thus are useful for 
storing collections of objects of CObject-derived classes. If such a collection is ar- 
chived or sent to a diagnostic dump context, then the element objects are automat- 
ically processed. For more about collection classes, see Section 2.4 later in this 
chapter. 


2.3 File Classes 


The CFile family of classes provides a C++ programming interface to operating- 
system files. The CFile class itself gives access to low-level binary files, and the 
CStdioFile class gives access to buffered “standard I/O” files. CStdioFile files are 
often processed in “text mode,” which means that newline characters are con- 
verted to carriage return—linefeed pairs on output. 


CMemFile supports “in-memory” files. The files behave like disk files except that 
bytes are stored in RAM. An in-memory file is a useful means of transferring raw 
bytes or serialized objects between independent processes. 


Because CFile is the base class for all file classes, it provides a polymorphic pro- 
gramming interface. If a CStdioFile file is opened, for example, its object pointer 
can be used by the virtual Read and Write member functions defined for the 
CFile class. 


The CDumpContext and CArchive classes, described previously, depend on the 
CFile class for input and output. 


2.4 Collection Classes 


The Microsoft Foundation Class Library contains a number of ready-to-use lists, 
arrays, and maps that are referred to as “collection classes.” A collection is an 
extremely useful programming idiom for holding and processing groups of objects 
or standard types. C++ makes a collection appear as a single object, so collection 
member functions can operate on all elements of the collection. 


All collections may be archived or sent to a dump context. The Dump and 
Serialize member functions for CObject pointer collections call the correspond- 
ing functions for each of their elements. 

If you need a list, array, or map that is not included among the 16 standard collec- 
tions provided with the Microsoft Foundation classes, then you can use the 
Templdef template tool that is included in the sample directory. The disk file 


Lists 


Arrays 


Maps 
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MFC\DOC\TNO004.TXT contains a guide to the use of this tool. The hierarchy 
chart of the Microsoft Foundation classes shown at the beginning of Part 2 indi- 
cates these three collection templates: “CArray<TYPE>,” “CList<TYPE>,” and 
“CMap<KEY, VALUE>.” 


There are “list” classes for CString objects, CObject pointers, and void pointers. 
A list is an ordered grouping of elements. New elements can be added at the head 
or tail of the list, or before or after a specified element. The list can be traversed in 
forward or reverse sequence, and elements may be removed during the traversal. 
Elements can be found by zero-based index or by value, but the find operation 
requires a sequential scan of the list. 


The Microsoft Foundation Class Library contains “array” classes for bytes, words, 
double words, CString objects, CObject pointers, and void pointers. An array is a 
dynamically sized grouping of elements that are directly accessible through a zero- 
based integer subscript. If a new element is inserted into an array, then the ele- 
ments above the insertion point are moved up. If an element above the current 
array bound is to be set, then the programmer can specify whether the array is to 
grow automatically. The subscript ({ ]) operator can be used to set or retrieve array 
elements. 


When growing is not required, array collection access is just as fast as standard C 
array access. The added storage overhead is insignificant. 


A “map” is a dictionary that maps keys to values. Seven map classes support 
CString objects, words, CObject pointers, and void pointers. Consider the 
CMapWordToOb class as an example. A WORD variable is used as a key to 
find the corresponding CObject pointer. Duplicate key values are not allowed. A 
key-pointer pair can be inserted only if the key is not already contained in the map. 


Key lookups are fast because they rely on a hashing technique. A map can be 
traversed, but the retrieval sequence 1s indeterminate. It makes sense, then, to it- 
erate over all the elements in a map. 


28 The Class Libraries Reference 


2.9 Miscellaneous Support Classes 


The Microsoft Foundation CString, CTime, and CTimeSpan classes are not 
derived from CObject. They are discussed below. 


The CString Class 


The CString class supports dynamic character strings. CString objects can grow 
and shrink automatically, and they can be serialized. Member functions and over- 
loaded operators add Basic-like string-processing capability. These features make 
CString objects easier to use than C-style fixed-length character arrays. Conver- 
sion functions allow CString objects to be used interchangeably with C-style 
strings. Thus a CString object can be passed to a function that expects a pointer to 
a constant string (const char*) parameter. 


Like other Microsoft Foundation classes, the CString class allocates memory on 
the heap. You must be sure that CString destructors are called at appropriate 
times in order to free unneeded memory. There is no automatic “garbage collec- 
tion” as there is in Basic. 


The CTime and CTimeSpan Classes 


The CTime class encapsulates the run-time time_t data type. Thus it represents 
absolute time values in the range 1900 to 2036, approximately. There are member 
functions that convert a time value to years, months, days, hours, minutes, and sec- 
onds. The class has overloaded insertion and extraction operators for archiving 

and for diagnostic dumping. 


The CTimeSpan class extends time_t by representing relative time values. If two 
CTime objects are subtracted, the result is a CTimeSpan object. A CTimeSpan 
object can be added to or subtracted from a CTime object. A CTimeSpan value is 
limited to the range of + 68 years, approximately. 


2.6 Diagnostic Services 


Several non-class-related functions and macros that provide diagnostic services 
are available. Most of these require the Debug version of the Microsoft Founda- 
tion Class Library and thus should not be used in released applications. For a 
detailed description of the functions and macros available, see Chapter 4, “Diag- 
nostic Services.” 
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Memory Diagnostics 


Most applications use the C++ new operator to allocate memory on the heap. The 
Microsoft Foundation classes provide a special Debug version of new that inserts 
extra control bytes in allocated memory blocks. These control bytes, together with 
the run-time class information that results from CObject derivation, allow you to 
analyze memory allocation statistics and detect memory block bounds violations. 


A memory dump can include the source filename and the line number of the allo- 
cated memory, and, in the case of objects from CObject-derived classes, the name 
of the class and the output from its Dump function. 


Diagnostic Output 


Assertions 


Most programmers want diagnostic output statements in their programs, particu- 
larly during the early stages of development. The TRACE statement acts like 
printf except that it has no effect with the Release version of the library. In the 
Windows environment, debugging output goes to the CodeView debugger if it is 
present; otherwise it goes to device AUX. 


You can use the afxDump dump context object for stream-style dumping of stand- 
ard types as well as Microsoft Foundation class objects. If you use afxDump, be 
sure to bracket references with #ifdef _DEBUG and #endif statements. 


In the Debug environment, the ASSERT macro evaluates a specified condition. If 
the condition is false, the macro prints the source filename and the line number, 
then it terminates the program . In the Release environment, the statement has no 
effect. 


VERIFY, a companion macro, evaluates the condition in both the Debug and 
Release environments. It prints and terminates only in the Debug environment. 


With Windows, ASSERT and VERIFY display their messages in a pop-up 
dialog box. 


2./ Exception Handling 


The Microsoft Foundation Class Library includes an exception-handling mecha- 
nism, similar to the one in the proposed ANSI C++ standard, for handling “abnor- 
mal conditions.” An abnormal condition is defined as a condition outside the 
program’s control that influences the outcome of a function. Abnormal conditions 
include low memory, I/O errors, and attempted use of an unsupported feature. 
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They do not include programming errors or “normally expected” conditions such 
as end of file. 


For exception-processing examples and a more detailed explanation of error cate- 
gories, see Chapter 12, “Exceptions,” in the Class Libraries User’s Guide. For a 
detailed description of the functions and macros available, see Chapter 5 of this 
book, “Exception Processing.” | 


Exception Classes and Macros 


Exception handling in the Microsoft Foundation classes relies on “exception ob- 
jects” and a group of macros. The process starts with the interruption of normal 
program execution in response to a THROW statement (macro invocation). Ex- 
ecution resumes at the appropriate CATCH statement leading into code that pre- 
sumably deals with the abnormal condition. The exception objects, which are 
instances of classes derived from CException, differentiate the various kinds of 
exceptions and are used for communication. 


This exception-handling scheme eliminates the need for extensive error testing 
after every library function call. If, for example, you enclose your entire program 
in an exception-handling block, then you don’t have to test for low memory after 
each statement that contains the new operator. 


If you don’t provide exception-processing code in your classes, then exceptions 
will be caught in the Microsoft Foundation code. This results in termination of the 
program through the global function AfxTerminate, which normally calls the run- 
time function abort. You can use the AfxSetTerminate function to change the 
effect of AfxTerminate. 


When to Use Exception Handling 


Out-of-memory and disk-full conditions could occur any time during program 
execution. A TRY/CATCH sequence at the top level of your application can pro- 
vide a warning message to the user, followed by a graceful exit. 


Routine file exceptions can occur at a lower level in the application. If your pro- 
gram attempts to open a nonexistent file, local CATCH logic can inform the user 
or take other corrective action. A better alternative, however, might be an explicit 
test for the file’s presence. 


If you want your program to keep running after the exception, be eee careful to 
clean up memory by deleting unused objects. Don’t forget CString objects that 
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have been allocated on the stack. 


Macros and Global Functions 


This chapter briefly describes the macros and global functions available to 
simplify your programming with the Microsoft Foundation Class Library. Most 
programmers will find that the macros presented here meet most of their needs. 
Advanced programmers may wish to use some of the global functions provided 
for special needs. 


All macros are listed in alphabetical order, followed by all global functions in al- 
phabetical order. A few items not documented elsewhere are documented follow- 
ing the alphabetical listings. 


For easy reference, the following table shows where to find related discussion and 
examples in other parts of the Class Libraries Reference and in the Class Libraries 
User’s Guide: 


Category Reference Chapter User’s Guide Chapter 
Diagnostics Chapter 4 Chapter 2 

Exceptions Chapter 5 Chapters 2 and 12 
Message Map Chapter 6 Chapters 3 and 14 
Run-Time Class CObject Chapter 8 

Information 


Serialization CObject Chapter 10 
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3.1 Alphabetical Listing of Macros 


To find additional discussion and examples for a macro, see the table above, using 
the category specified in the macro description below. Macros documented in this 
section, in addition to the locations shown in the table, are indicated by the phrase 
“Details follow.” 


AND_ CATCH 
Designates a block of code for catching the second or subsequent exception 
from the preceding TRY block. 


For additional information, see the Exceptions category in the table. 


ASSERT 
Prints a message and aborts the application if the specified expression evaluates 
to FALSE in the Debug version of the library. 


For additional information, see the Diagnostics category in the table. 


ASSERT_ VALID 
Tests the internal validity of an object by calling its AssertValid member func- 
tion, typically overridden from CObject. 


For additional information, see the Diagnostics category in the table. 


BEGIN_ MESSAGE_ MAP 
Sets up the message map for a window class. 


For additional information, see the Message Map category in the table. 


CATCH 
Designates a block of code for catching the first exception from the preceding 
TRY block. 


For additional information, see the Exceptions category in the table. 


DEBUG_NEW 
Helps find memory leaks by providing a filename and line number for all object 
allocations in Debug mode. Details follow. 


For additional information, see the Diagnostics category in the table. 


DECLARE_DYNAMIC 
Prepares a class so that you can determine its name, the name of its base class, 
and other information at run time. Details follow. 


For additional information, see the Run-Time Information category in the table. 


DECLARE_MESSAGE_ MAP 
Associates a message map with a window class declaration. 


For additional information, see the Message Map category in the table. 
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DECLARE_SERIAL 
Prepares a class to serialize its data to and from persistent storage. Details 
follow. 


For additional information, see the Serialization category in the table. 


END_ CATCH 
Ends the last CATCH or AND_ CATCH block in an exception frame. 


For additional information, see the Exceptions category in the table. 


END_MESSAGE_MAP 
Completes a message-map definition for a window class. 


For additional information, see the Message Map category in the table. 


IMPLEMENT_DYNAMIC 
Enables a class so that you can determine its run-time information. Details 
follow. 


For additional information, see the Run-Time Information category in the table. 


IMPLEMENT_SERIAL 
Enables the ability of a class to serialize its data to and from persistent storage. 
Details follow. 


For additional information, see the Serialization category in the table. 


RUNTIME_CLASS 
Returns a CRuntimeClass object from which you can extract run-time informa- 
tion about a specified class. Details follow. 


For additional information, see the Run-Time Information category in the table. 


THROW 
Throws a specified exception. 


For additional information, see the Exceptions category in the table. 


THROW_LAST 
Invokes the exception handler in the next outer frame. 


For additional information, see the Exceptions category in the table. 


TRACE 
Provides a printf-like capability in the Debug version of the library. 


For additional information, see the Diagnostics category in the table. 


TRY 
Designates a block of code for exception processing. 


For additional information, see the Exceptions category in the table. 


VERIFY 
Similar to ASSERT but evaluates the expression in the Release version of the 
library as well as in the Debug version. | 


For additional information, see the Diagnostics category in the table. 
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3.2 Alphabetical Listing of Global Functions — 
To find additional discussion and examples for a global function, see the preced- 


ing table, using the category specified in the function description below. Functions 
that are documented in this section are indicated by the phrase “Details follow.” 


AfxAbort 
The default function called by AfxTerminate. 


For additional information, see the Exceptions category in the table. 


AfxCheckMemory 
Checks all currently allocated memory for corrupted guard bytes. 


For additional information, see the Diagnostics category in the table. 


AfxDoForAllClasses 
Performs a specified function on all classes derived from CObject that support 
run-time type checking and are used by the running program. 


For additional information, see the Diagnostics category in the table. 


AfxDoForAllObjects 
Performs a specified function on all objects derived from CObject that support 
run-time type checking and are used by the running program. 


For additional information, see the Diagnostics category in the table. 


AfxEnableMemoryTracking 
Turns memory tracking on and off. 


For additional information, see the Diagnostics category in the table. 


AfxGetApp 
Returns a pointer to the application’s one CWinApp object. Details follow. 


AfxGetAppName 
Returns a string containing the application’s name. Details follow. 


AfxGetInstanceHandle 
Returns a HANDLE to the current instance of the application. Details follow. 


AfxGetResourceHandle 
Returns a HANDLE to the current instance of the application. Use this handle 
to access the application’s resources directly. Details follow. 


AfxIsMemoryBlock 
Verifies that a memory block has been properly allocated. 


For additional information, see the Diagnostics category in the table. 


AfxIsValidAddress 
Verifies that a memory block is within the program’s bounds. 


For additional information, see the Diagnostics category in the table. 
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AfxRegisterWndClass 
Registers a Windows window class to supplement those registered automat- 
ically by the library. Details follow. 


For additional information, see the Class Libraries User’s Guide, Chapter 14, 
“Window Management.” 


AfxSetAllocHook 
Enables the calling of a function on each memory allocation. 


For additional information, see the Diagnostics category in the table. 


AfxSetAllocStop 
Enables the calling of a function on the nth memory allocation. 


For additional information, see the Diagnostics catgeory in the table. 


AfxSetTerminate 
Sets the final destination of calls to AfxTerminate. 


For additional information, see the Exceptions category in the table. 


AfxTerminate 
Called internally if there is no applicable TRY/CATCH frame in effect. 


For additional information, see the Exceptions category in the table. 


AfxThrowArchiveException 
Throws an archive exception. 


For additional information, see the Exceptions category in the table. 


AfxThrowFileException 
Throws a file exception. 


For additional information, see the Exceptions category in the table. 


AfxThrowMemoryException 
Throws a memory exception. 


For additional information, see the Exceptions category in the table. 


AfxThrowNotSupportedException 
Throws a not-supported exception. 


For additional information, see the Exceptions category in the table. 


AfxThrowResourceException 
Throws a Windows resource-not-found exception. 


For additional information, see the Exceptions category in the table. 
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3.30 Macros and Global Functions Not Documented Elsewhere 


Syntax — 


Remarks 


Return Value 


Syntax 


Remarks 


Return Value 


Syntax 
Remarks 


Return Value 


AfxGetApp 


CWinApp* AfxGetApp(); 


Returns a pointer to the one and only CWinApp object for the Windows applica- 
tion. This pointer is useful for getting access to the main message dispatch code or 
the topmost window. 


A pointer to a CWinApp object. 


AfxGetAppName 
const char* AfxGetAppName( ); 


Returns a null-terminated string containing the Windows application’s name. This 
string is useful for diagnostic messages or as a root for temporary string names. 


A null-terminated string containing the application’s name. 


AfxGetinstanceHandle 
HANDLE AfxGetInstanceHandle( ); 
Returns a HANDLE to the current instance of the Windows application. 


A HANDLE to the current instance of the application. 


Syntax 


Remarks 


Return Value 


Syntax 


Parameters 


Remarks 
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AfxGetResourceHandle 
HANDLE AfxGetResourceHandle( ); 


Returns a HANDLE to the current instance of the Windows application. Use this 
handle to access the application’s resources directly, for example in calls to the 
Windows function FindResource. 


Note Override and reimplement this function if you wish to load your resources 
from a DLL. 


A HANDLE to the current instance of the application. 


AfxRegisterWndClass 


const char* AfxRegisterWndClass( UINT nClasstyle, HCURSOR /hCursor = 0, 
HBRUSH hbrBackground = 0, HICON hicon = 0); 


nClasstyle | 
The Windows class style or combination of styles for the window class. This 
parameter can be any valid window style or control style, or a combination of 
styles created by using the bitwise-OR (| ) operator. 


hCursor 
A handle to the cursor resource to be installed in each window created from the 
window class. 


hbrBackground | 
A handle to the brush resource to be installed in each window created from the 
window class. 


hIcon 
A handle to the icon resource to be installed in each window created from the 
window class. 


Although the Microsoft Foundation Class Library automatically registers several 
standard window classes for you, you can call this function to register your own 
window classes. You may also use the function to change the application’s icon, 
although a simpler way is discussed in the Class Libraries User’s Guide. For addi- 
tional information, see Chapter 14, “Window Management.” See that chapter as 
well for more information about using AfxRegisterWndClass, and see Technical 
Note 1, in the file TN0O01.TXT on the distribution disks. 
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Return Value 


Syntax 


Remarks 


Syntax 


Parameters 


A null-terminated string containing the class name. You can pass this class name 
to the CWnd::Create member function to create a window. The name is 
generated by the Microsoft Foundation Class Library. 


Note The return value is stored in a static buffer. To save this string, assign it to a 
CString variable. 


DEBUG_NEW Macro 


#define new DEBUG_NEW 


Use to assist in finding memory leaks. You can use DEBUG_ NEW everywhere 
in your program that you would ordinarily use the new operator to allocate heap 
storage. 


In Debug mode (when the _ DEBUG symbol is defined), DEBUG_ NEW keeps 
track of the filename and line number for each object that it allocates. Then, when 
you use the DumpAIl]Objectsince member function of class CMemoryState, 
each object allocated with DEBUG_ NEW is shown with the filename and line 
number where it was allocated. 


To use DEBUG_ NEW, insert the define directive shown in the syntax line above 
into your source files. Then wherever you use new, the preprocessor will insert 
DEBUG_NEW, and the class library does the rest. When you compile a release 
version of your program, DEBUG_NEW resolves to a simple new operation, and 
the filename and line number information is not generated. 


Note In Release mode, DEBUG_NEW is defined to be the standard operator 
new, so you can leave DEBUG_NEW in your code. 


DECLARE_DYNAMIC Macro 


DECLARE_DYNAMIC( className ); 


className 
The name of the class that you want to be compliant with the ability of class 
CObject to supply dynamic run-time class information. 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 
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Any class derived from class CObject can supply run-time information about it- 
self and its base class, provided you invoke the DECLARE_ DYNAMIC and 
IMPLEMENT_DYNAMIC macros. This means you can determine the exact 
class of an object at run time and also determine the base class from which it was 
derived. 


Put the DECLARE_ DYNAMIC macro in your class declaration. Put the 
IMPLEMENT_DYNAMIC macro in your .CPP file. These macros add code to 
your class to enable dynamic run-time information. 


You can access the dynamic information about a class with the IsKindOf member 
function of class CObject and with the RUNTIME_ CLASS macro. This run- 
time information is available and valid only for classes that have a single base 
class. For more information and examples, see the Class Libraries User’s Guide, 
Chapter 8, “The CObject Class.” 


IMPLEMENT_DYNAMIC, RUNTIME_ CLASS, CObject 


DECLARE SERIAL Macro 


DECLARE_SERIAL( className ) 


className 
The name of the class that is to have serialization capability. 


Classes that are derived from CObject can take advantage of the ability of 
CObject ability to write its members to a persistent storage medium, such as a 
disk file, and to read its persistent data back in. 


DECLARE_SERIAL includes dynamic type information as well, so you don’t 
need DECLARE_ DYNAMIC if you use DECLARE_ SERIAL. 


To take advantage of this ability, a derived class must use the 
DECLARE_SERIAL macro in its class declaration and the corresponding 
IMPLEMENT_SERIAL macro in its .CPP file. The class must also override the 
Serialize member function of class CObject. 
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See Also 


Syntax 


Parameters 


Remarks 


See Also 


syntax 


Parameters 


Put the DECLARE_SERIAL macro at the beginning of your derived class decla- 
ration. For more discussion and examples, see the Class Libraries User’s Guide, 
Chapter 2, “Creating a Data Model with the Microsoft Foundation Classes,” and 
Chapter 10, “Files and Serialization.” 


IMPLEMENT_SERIAL 


IMPLEMENT_DYNAMIC Macro 


IMPLEMENT_DYNAMIC( className, baseClassName ) 


className 
The name of the class that you want to be compliant with the ability of class 
CObject to supply dynamic run-time information. 


baseClassName 
The name of the base class of your compliant class. 


Use in your .CPP file in conjunction with the DECLARE_ DYNAMIC macro in 
your .H file to allow your class to supply dynamic run-time information. This al- 
lows you to query an object with the IsKindOf member function in class CObject 
to determine its class and base class names. For discussion and examples, see the 
Class Libraries User’s Guide, Chapter 8, “The CObject Class.” 


DECLARE_DYNAMIC, CObject 


IMPLEMENT_SERIAL Macro 


IMPLEMENT_SERIAL( className, baseClassName, schemaNumber ) 


className 
The name of the class that is to have the ability to serialize its members to per- 
sistent storage. 


baseClassName 
The name of the base class of the serializable class. 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


Example 
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schemaNumber 
The version number for objects of this class. If you modify a class, you can 
assign it a higher schema. Then, during serialization from storage to memory, if 
the schema number of the object on disk does not match that of the class in 
memory, an exception is thrown. This prevents you from reading an incorrect 
version of an object. The schema number is an integer greater than or equal to 0. 


Use in your .CPP file to correspond to the DECLARE_SERIAL macro in your 
.H file. This macro adds the necessary code to permit a class to serialize its mem- 
bers. You must also override the Serialize member function of class CObject. 


DECLARE_SERIAL, CObject::Serialize, CObject 


RUNTIME CLASS Macro 


RUNTIME_CLASS( className ) 


className 
The name of the class that you want run-time class information. 


Use to extract the run-time class information for a specified class derived 

from CObject. The macro returns an object of class CRuntimeClass. A 
CRuntimeClass structure has member variables containing the class name, object 
size, schema number, base class, and other information, which you can access 
directly. CRuntimeClass is defined in the file AFX.H. You can also use the 
IsKindOf member function of class CObject to query whether an object belongs 
to a specified class. For more information and examples, see the Class Libraries 
User’s Guide, Chapter 8, “The CObject Class.” 


CObject::IsKindOf, CRuntimeClass, CObject 


CRuntimeClass* pCls; 
pCls = RUNTIME_CLASS( CObject ); 


Diagnostic Services 


This chapter describes a group of macros and global functions that provide diag- 
nostic services. All these functions, except as noted, require the Debug version of 
the Microsoft Foundation Class Library. 


In the Debug library, all allocated memory blocks are bracketed with a series of 
“suard bytes.” If these bytes are disturbed by an errant memory write, then the 
diagnostic routines can report the problem. 


If you include the line 


#tdefine new DEBUG NEW 


in your implementation file, then all calls to new will store the filename and line 
number where the memory allocation took place. The DumpAllObjectsSince 
function of the CMemoryState class will display this extra information, thus 
greatly simplifying the identification of memory leaks. 


Since many of these diagnostic functions are designed for tracking memory errors, 
you should refer to the “Memory Management” section in Chapter 7 of the Class 
Libraries User’s Guide for a discussion of memory allocation for both MS-DOS 
and Windows while using the Microsoft Foundation Class Library. Refer also to 
the class CDumpContext for additional information on diagnostic output. The 
cookbook section of the Class Libraries User’s Guide, “Detecting Memory 
Leaks” (page 290), illustrates the use of several key memory-diagnostic functions. 


For a general discussion of diagnostic facilities, see Chapter 11, “Diagnostics,” in 
the Class Libraries User’s Guide. 


To use these macros and global functions, add the following directives to the top 
of your program: 


#define _DEBUG 


#include <afx.h> 
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4.1 General Diagnostic Macros 


The following list describes general diagnostic macros: 


ASSERT 
Prints a message if the specified expression evaluates to FALSE in the Debug 
version of the library, and then aborts the program. 


ASSERT_ VALID 
Tests the internal validity of an object by calling its AssertValid member func- 
tion, typically overridden from CObject. 


TRACE 
Provides printf-like capability in the Debug version of the library. 


VERIFY 
Similar to ASSERT but evaluates the expression in the Release version of the 
library as well as in the Debug version. 


4.2 General Diagnostic Functions 


The following list describes general diagnostic functions: 


afxMemDF 
Global variable that controls the behavior of the debugging memory allocator. 


AfxCheckMemory 
Checks all currently allocated memory for corrupted guard bytes. 


AfxEnableMemorytTracking 
Turns memory tracking on and off. 


AfxIsMemoryBlock 
Verifies that a memory block has been properly allocated. 


AfxIs ValidAddress 
Verifies that any memory block is within the program’s bounds. 


AfxSetAllocHook 
Enables the calling of a function on each memory allocation. 


AfxSetAllocStop 
Enables the calling of a function on the nth memory allocation. 


Checkpoint 
A CMemoryState member function that checkpoints a memory state. 


CMemoryState 
Constructor for a class-like structure that controls memory checkpointing. 
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Difference 
A CMemoryState member function that computes the difference between two 
checkpointed memory states. 


DumpAllObjectsSince 
A CMemoryState member function that dumps all currently allocated objects 
since the last checkpoint. 


DumpStatistics 
A CMemoryState member function that prints memory allocation statistics. 


4.3 Object Diagnostic Functions 


The following list describes object diagnostic functions: 


AfxDoForAllClasses 
Performs a specified function on all CObject-derived classes that support 
run-time type checking by using the DECLARE_ DYNAMIC or 
DECLARE_SERIAL macros. 


AfxDoForAllObjects 
Performs a specified function on all CObject-derived objects that support run- 
time type checking. 
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4.4 Global Variables 


Syntax 


Remarks 


Example 


afxMemDF 


int afxMemDF; 


An integer variable, easily accessible from a debugger, that tunes the allocation 
diagnostics. It can have the following values as specified by the enumeration 
afxMemDF: 


allocMemDF Turns on debugging allocator (default setting 
in Debug library). 
delayFreeMemDF Delays freeing memory. While your program 


frees a memory block. 


checkAlwaysMemDF Calls AfxCheckMemory every time memory 
is allocated or freed. This will significantly 
slow memory allocations and deallocations. 


afxMemDF = delayFreeMemDF | checkAlwaysMemDF ; 
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4.5 Functions and Macros 


AfxCheckMemory 


Syntax BOOL PASCAL AfxCheckMemory(); 


Remarks Iterates through all memory blocks currently allocated on the heap. These blocks 
include those allocated by new, but not those allocated by direct calls to underly- 
ing memory allocators such as malloc or ::GlobalAlloc. If any block is found to 
have corrupt guard bytes, a message is printed on stderr. 


If the block contains an object of a class derived from CObject, then the function 
reports an Object, otherwise it reports a Non-Object. It always reports an 
address that corresponds to the address printed by DumpAIlObjectsSince. 


Additionally, the function validates the free memory pool, printing error messages 
as required. 


If the function detects no memory corruption, it prints nothing. 
If you include the line 


d#tKdefine new DEBUG_NEW 


in a program module, then subsequent calls to AfxCheckMemory show the 
filename and line number where the memory was allocated. 


Note If your module contains one or more implementations of serializable 


classes, then you must put the new redefinition statement after the last 
IMPLEMENT_SERIAL macro invocation. 


Return Value TRUE if no memory errors; otherwise FALSE. 
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Example CAge* pcage = new CAge( 21 ); // CAge is derived from CObject 
Agex page = new Age( 22 ); // Age is NOT derived from CObject 
*(((char*) pcage) - 1) = 99; // Corrupt preceding guard byte 
*(((char*) page) - 1) = 99; // Corrupt preceding guard byte 
AfxCheckMemory(); 


/* Tr ¥ Pod A Uh ReErcse UE Fs 

memory check error at $0067495F = $63, should be $FD 
DAMAGE: before Non-Object block at $00674960 
Non-Object allocated at file test@2.cxx(48) 
Non-Object located at $00674960 is 2 bytes long 


memory check error at $00674905 = $63, should be $FD 
DAMAGE: before Object block at $00674906 

Object allocated at file test@2.cxx(47) 

Object located at $00674906 is 4 bytes long 

* / 


AfxDoForAllClasses 


Syntax void PASCAL AfxDoForAllClasses( void (*pfn)(const CRuntimeClass* pClass, 
void* pContext), void* pContext ); 


Parameters pjn 
A pointer to an iteration function to execute for each class. The function argu- 
ments are a pointer to a CRuntimeClass object and an optional void pointer to 
extra data that the caller supplies to the function. 


pClass 
A pointer to a CRuntimeClass object. AfxDoForAllClasses uses this parame- 
ter to pass each eligible class in turn to the iteration function. - 


pContext 
A pointer to optional data that the caller can supply to the iteration function. 


Remarks Executes the specified iteration function for all CObject-derived classes in 
the application’s memory space that support run-time type checking using the 
DECLARE_DYNAMIC or DECLARE_SERIAL macros. The pointer passed 
to AfxDoForAlIClasses in pContext is passed to the specified iteration function 
each time it is called. 


Note This function only works in the Debug version of the library. 


Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Remarks 


Return Value 
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AfxDoForAllObjects 


void PASCAL AfxDoForAllObjects( void (*pfn)(CObject* pObject, 
void* pContext), void* pContext ); 


pfn 


A pointer to an iteration function to execute for each object. The function argu- 
ments are a pointer to a CObject and an optional void pointer to extra data that 
the caller supplies to the function. 

pObject 
A pointer to an object of class CObject or a class derived from it. 
AfxDoForAllObjects uses this parameter to pass each eligible object in turn to 
the iteration function. 


pContext 
A pointer to optional data that the caller can supply to the iteration function. 


Executes the specified iteration function for all objects derived from CObject in 
the application’s memory space. The objects must have been allocated with new; 
stack objects are not enumerated. The pointer passed to AfxDoForAllClasses in 
pContext is passed to the specified iteration function each time it is called. 


Note This function only works in the Debug version of the library. 


AfxEnableMemoryTracking 
BOOL PASCAL AfxEnableMemoryTracking( BOOL bTrack ); 


bTrack 
TRUE turns on memory tracking; FALSE turns it off. 


Diagnostic memory tracking is normally enabled in the Debug version of the 
Microsoft Foundation classes. Use this function to disable tracking on sections of 
your code that you know are allocating blocks correctly. 


The previous setting of the tracking-enable flag. 
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Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


AfxisMemoryBlock 


BOOL PASCAL AfxIsMemoryBlock( const void* p, UINT nBytes, 
LONG* plRequestNumber = NULL ); 


Pp 
A Void pointer to the block of memory to be tested. 


nBytes 
The length of the memory block in bytes. 


plRequestNumber 
A pointer to a long integer that will be filled in with the memory block’s alloca- 
tion sequence number. The variable pointed to by plRequestNumber will only 
be filled in if AfxIsMemoryBlock returns TRUE. 


Tests a memory address to make sure it represents a currently active memory 
block that was allocated by the diagnostic version of new. It also checks the 
specified size against the original allocated size. The allocation sequence number 
that is returned in plRequestNumber if the function returns TRUE is the order in 
which the block was allocated relative to all other new allocations. 


TRUE if the memory block is currently allocated and the length is correct; other- 
wise FALSE. | 


CAge*x pcage = new CAge( 21 ); // CAge is derived from CObject 
if( AfxIsMemoryBlock( pcage, sizeof( CAge ) ) != TRUE ) 
exit( 1 ); // Invalid memory 


AfxIsValidAddress 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


Syntax 


Parameters 
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AfxisValidAddress 


BOOL FAR PASCAL AfxIsValidAddress( const void FAR* /p, UINT nBytes, 
BOOL bReadWrite = TRUE ); 


Ip 
Points to the block of memory to be tested. 


nBytes 
Contains the length of the memory block in bytes. 


bReadWrite 
Specifies whether the memory is both for reading and writing. 


Tests any memory block to ensure that it is contained entirely within the pro- 
gram’s memory space. The address is not restricted to blocks allocated by new. 


Note With MS-DOS real mode, only addresses with null selectors are invalid; all 
others are valid. A huge pointer cast to a FAR pointer cannot be used as a parame- 
ter to AfxIs ValidAddress. 


TRUE if the specified memory block is contained entirely within the program’s 
memory space; otherwise FALSE. 


char* pbuf = (char*) malloc( 1@ ); 
if( AfxIsValidAddress( pbuf, 10, TRUE ) != TRUE ) 
exit( 1 ); // Invalid memory 


AfxIsMemoryBlock 


AfxSetAllocHook 


AFX_ALLOC_ HOOK AfxSetAllocHook( AFX_ ALLOC_HOOK 
pfnAllocHook ); 


pfnAllocHook 
The name of the function to call. The function must return a BOOL value and 
accept size_t, BOOL, and long arguments. 
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Remarks 


Hook Function 


Syntax 


Parameters 


Remarks 


Sets a hook that enables calling of the specified function each time memory is 
allocated. 


The hook function is described below. 


The Microsoft Foundation Class Library debug memory allocator can call a user- 
defined hook function to allow the user to control whether to permit the allocation. 


Allocation hook functions are prototyped as: 


BOOL AllocHook( size_t nSize, BOOL bObject, LONG [RequestNumber ); 


Parameter Description 

nSize The size of the proposed memory allocation. 

bObject TRUE if the allocation is for a CObject-derived object. 
l[RequestNumber The memory allocation’s sequence number. 


Return Value 
TRUE if you want to permit the allocation; otherwise FALSE. 


AfxSetAllocStop 


void PASCAL AfxSetAllocStop( LONG lRequestNumber ); 


[RequestNumber 
The sequence number of the memory allocation on which the program will halt. 


Each memory allocation is assigned a sequential serial number. This function 
forces the program to halt (using the INT 3 interrupt) on the specified memory al- 
location sequence number. This is useful if you are running the program from 
within a debugger. You can obtain the allocation sequence number to pass in 
[RequestNumber by calling AfxIsMemoryBlock. 


Syntax 


Parameters 


Remarks 


Example 


See Also 


Syntax 


Parameters 


Remarks 
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ASSERT Macro 


ASSERT( booleanExpression ); 


booleanExpression 
An expression (including pointer values) that evaluates to TRUE or FALSE. 


The ASSERT macro evaluates its argument. If the result is FALSE, the macro 
prints a diagnostic message and aborts the program. If the condition is TRUE, it 
does nothing. 


The diagnostic message has the form: 


assertion failed in file <name> in line <num> 


where name is the name of the source file, and num is the line number of the 
assertion that failed in the source file. 


In the Release environment, ASSERT does not evaluate the expression and thus 
will not interrupt the program. If the expression must be evaluated regardless of en- 
vironment, use the VERIFY macro in place of ASSERT. 


CAge* pcage = new CAge( 21 ); // CAge is derived from CObject 
ASSERT( pcage->IsKindOf( RUNTIME_CLASS( CAge ) ) ); 
// Terminates program only if pcage is NOT a CAge* 


VERIFY 


ASSERT_VALID Macro 


ASSERT_ VALID( object ); 


object 
An object of a class derived from CObject and with an overriding version of 
the AssertValid member function. 


Use to test your assumptions about the validity of an object’s internal state. 
ASSERT_ VALID calls the AssertValid member function of the object passed as 
its argument. By default, the Assert Valid member function of class CObject is 
called, but typically you override Assert Valid in classes that you derive from 
CObject so the overriding version will be called. In your Assert Valid override, 
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See Also 


Syntax 


Remarks 


Example 


Syntax 


Remarks 


Example 


you can test the object’s internal validity. For example, if the object represents a 
linked list, you could verify that the head and tail pointers are NULL if the list is 
empty and not NULL if the list is not empty. 


For more information and examples, see the Class Libraries User’s Guide, Chap- 
ters 4 and 11, “Phone Book: A Simple Windows Database,” and “Diagnostics.” 


ASSERT, VERIFY, CObject, CObject::AssertValid 


CMemoryState::Checkpoint 
void Checkpoint(); 


Takes a snapshot summary of memory and stores it in this CMemoryState object. 
The CMemoryState member functions Difference and DumpAllObjectsSince 
use this snapshot data. 


See the example for the CMemoryState constructor. 


CMemoryState::CMemoryState 
CMemoryState(); 


Constructs an empty CMemoryState object that must be filled in by the 
Checkpoint or Difference member functions. 


// Includes all CMemoryState functions 
CMemoryState cmOld, cmNew, cmDif; 
cm01d.Checkpoint(); 

CAge* pagel = new CAge( 21 ); 
CAge* page2 = new CAge( 22 ); 
cm01d.DumpAll10bjectsSince(); 
cmNew.Checkpoint(); 

cmDif .Difference( cmOld, cmNew ); 
cmDif.DumpStatistics(); 
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CMemoryState::Difference 


Syntax BOOL Difference( const CMemoryState& oldState, 
const CMemoryState& newState ); 


Parameters oldState 
The initial memory state, as defined by a CMemoryState checkpoint. 


newState 
The new memory state, as defined by a CMemoryState checkpoint. 


Remarks Compares two checkpointed CMemoryState objects, then stores the difference 
into this CMemoryState object. Checkpoint must have been called for each of 
the two memory-state parameters. 


Example See the example for the CMemoryState constructor. 


CMemoryState::DumpAllObjectsSince 


Syntax void DumpAllObjectsSince() const; 

Remarks Calls the Dump function for all objects of derived CObject classes that 
were allocated (and are still allocated) since the last Checkpoint call for this 
CMemoryState object. 


Use DumpAllObjectsSince in conjunction with AfxCheckMemory to match re- 
ported corrupted memory with the contents of the objects contained there. 


Calling DumpAllObjectsSince with an uninitialized CMemoryState object will 
dump out all objects currently in memory. 


Example See the example for the CMemoryState constructor. 
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Syntax 


Remarks 


Example 


Syntax 


Parameters 


Remarks 


Example 


CMemoryState::DumpStatistics 


void DumpStatistics( const; 


Prints, on afxDump, a concise memory statistics report from a CMemoryState 
object that is filled by the Difference member function. The report shows the 
following: 


# CObject blocks still allocated on the heap. 
Non-CObject blocks still allocated on the heap. 


= The maximum memory used by the program at any one time. 


The total memory currently used by the program. 


For a detailed description of the report, see the Class Libraries User’s Guide sec- 
tion “Detecting Memory Leaks,” on page 290. 


See the example for the CMemoryState constructor. 


TRACE Macro 


TRACE( exp ); 


exp 
A variable number of arguments used exactly in the same way as the run-time 
function printf uses them. 


In the Debug environment, the TRACE macro output goes to afxDump. In the Re- 
lease environment, it does nothing. This is a convenient way of generating debug- 
ging output that will appear only in the Debug version of your program. 


DG? ht os 

char sz[] = "one"; 

TRACE( "Integer = 4d, String = %s\\n", i, sz ); 
// Output: ‘Integer = 1, String = one’ 


Syntax 


Parameters 


Remarks 


Example 


See Also 
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VERIFY Macro 


VERIFY( booleanExpression ); 


exp 
An expression (including pointer values) that evaluates to TRUE or FALSE. 


In the Debug version of the Microsoft Foundation Class Library, the VERIFY 
macro evaluates its argument. If the result is FALSE, the macro prints a diagnos- 
tic message and halts the program. If the condition is TRUE, it does nothing. 


The diagnostic message has the form: 


assertion failed in file <name> in line <num> 


where name is the name of the source file and num is the line number of the 
assertion that failed in the source file. 


In the Release version of the Microsoft Foundation Class Library, VERIFY evalu- 
ates the expression but does not print or interrupt the program. For example, if the 
expression is a function call, the call will be made. 


CFile f; 
VERIFY( f.Open( "file.dat", CFile::modeCreate | CFile::modeWrite ) ); 
// Terminates program if Open fails; always executes Open 


ASSERT 


Exception Processing 


This chapter describes macros and global functions that relate to exception 
processing. 


For examples and more details, see the section “Exception Handling” (on page 61 
in Chapter 2) and the section “Catching Exceptions” (in Chapter 12, “Excep- 
tions’), both in the Class Libraries User’s Guide. You may also wish to refer to 
class CException, later in this book. 


Note The AfxThrow functions are equivalent to the THROW macro with the ap- 
propriate exception class as an argument. 


To use these macros and global functions, add the following directive at the top of 
your program: 


#include <afx.h> 


5.1 Exception Macros 


TRY 
Designates a block of code for exception processing. 


CATCH 
Designates a block for catching an exception from the preceding TRY block. 


AND_ CATCH 
Designates a block for catching additional exception types from the preceding 
TRY block. 


END_CATCH 
Ends the last CATCH or AND_ CATCH block. 
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THROW 
Throws a specified exception. 


THROW_ LAST 
Invokes the exception handler in the next outer frame. 


9.2 eeppon Throwing Functions 
AfxThrowArchiveException 
Throws an archive exception. 


AfxThrowFileException 
Throws a file exception. 


AfxThrowMemoryException 
Throws a memory exception. 


AfxThrowNotSupportedException 
Throws a not-supported exception. 


AfxThrowResourceException 
Throws a Windows resource-not-found exception. 


0.3 Termination Functions 
AfxTerminate 
Called internally if there is no applicable TRY/CATCH in effect. 


AfxSetTerminate 
Sets the final destination of calls to AfxTerminate. 


AfxAbort 
The default function called by AfxTerminate. 
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5.4 Functions and Macros 


AfxAbort 


Syntax void CDECL AfxAbort(); 
Remarks This is the default termination function supplied by the Microsoft Foundation 
classes. 
See Also AfxSetTerminate, AfxTerminate 
AfxSetTerminate 
syntax AFX_TERM_PROC AfxSetTerminate( AFX_TERM_ PROC proc ); 
Parameters proc 


The name of a termination function that will be called by AfxTerminate. 
Termination functions must take no arguments and return nothing. 


Remarks Links AfxTerminate to the specified function. The default termination function is 
AfxAbort. AfxTerminate is called internally by Microsoft Foundation member 
functions when there is a fatal error, such as an uncaught exception. 
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Example 


See Also 


Syntax 


Remarks 


See Also 


void MyTerminateProc() // Called instead of AfxAbort 


{ 
printf( "Out of memory!\\n" ); 
exit( 1 ); 
} 
void main() 
{ 
AfxSetTerminate( MyTerminateProc ); 
while ( 1 ) 
{ 
// new calls AfxTerminate if unsuccessful 
BYTE * p = new BYTE[1024]; // Consume memory 
printf( “consumed memory at $%x\\n", p ); 
} 
} 


AfxAbort, AfxTerminate 


AfxTerminate 


void CDECL AfxTerminate(); 


Called internally by Microsoft Foundation member functions when there is a fatal 
error, such as an uncaught exception. Normally, Afx Terminate calls AfxAbort, 
but you can use AfxSetTerminate to enable the calling of a different function. 


You can call AfxTerminate any time you encounter an error from which you can- 
not recover. 


AfxAbort, AfxSetTerminate 


Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Remarks 


See Also 
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AfxThrowArchiveException 
void PASCAL AfxThrowArchiveException( int cause ); 


cause | 
An integer that indicates the reason for the exception. For a list of the possible 
values, see CArchiveException::m_ cause 


Throws CArchiveException. This is a helper function used in the implementation 
of the Microsoft Foundation classes. 


AfxThrowFileException 
void PASCAL AfxThrowFileException( int cause, LONG /OsError = —-1 ); 


cause 
An integer that indicates the reason for the exception. For a list of the possible 
values, see CFileException::m_ cause. 


lOsError 
An operating-system-specific reason for the exception, if available. The 
lOsError parameter provides more information than cause. 


Throws a CFileException. You are responsible for determining the cause based 
on the operating system error code. This is a helper function used in the implemen- 
tation of the Microsoft Foundation classes. 


Call this function when you implement your own low-level file operations in a 
derived file class. 


CFileException::ThrowOsError 
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Syntax 


Remarks 


Syntax 


Remarks 


Syntax 


Remarks 


AfxThrowMemoryeException 
void PASCAL AfxThrowMemoryException(); 


Throws a CMemoryException. This is a helper function used in the implementa- 
tion of the Microsoft Foundation classes. 


Call this function if calls to underlying system memory allocators (such as malloc 
and ::GlobalAlloc) fail. You do not need to call it for new because new makes the 
call internally. 


AfxThrowNotSupportedException 
void PASCAL AfxThrowNotSupportedException(); 


Throws a CNotSupportedException. This is a helper function used in the im- 
plementation of the Microsoft Foundation classes. 


AfxThrowResourceException 
void PASCAL AfxThrowResourceException(); 


Throws a CResourceException. It is normally called when a Windows resource 
cannot be loaded. This is a helper function used in the implementation of the 
Microsoft Foundation classes. 


Note This function requires the statement #include <afxwin.h>. 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 
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AND_CATCH Macro 


AND_CATCH( exception_class, exception_object_pointer_name ) 


exception_class 
The specific exception type to test for. For a list of standard exception classes, 
see CException. 


exception_object_pointer_name 
A name for an exception object pointer that will be created by the macro. 
You can use the pointer name to access the exception object within the 
AND_ CATCH block. 


Defines a block of code for catching additional exception types thrown 1n a preced- 
ing TRY block. Use the CATCH macro to catch one exception type, then the 
AND_CATCH macro to catch each subsequent type. 


The exception-processing code can interrogate the exception object, if appropriate, 
to get more information about the specific cause of the exception. Invocation of 
the THROW_LAST macro within the AND_ CATCH block shifts processing to 
the next outer exception frame. 


Note The AND_CATCH block is defined as a C++ scope (delineated by curly 
braces). If you declare variables in this scope, remember that they are accessible 
only within that scope. 


AND_CATCH marks the end of the preceding CATCH or AND_ CATCH block. 


TRY, CATCH, THROW, END_ CATCH, THROW_LAST 


CATCH Macro 


CATCH( exception_class, exception_object_pointer_name ) 


exception_class 
The specific exception type to test for. For a list of standard exception classes, 
see CException. 


exception_object_pointer_name 
A name for an exception object pointer that will be created by the macro. You 
can use the pointer name to access the exception object within the CATCH 
block. 
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Remarks 


See Also 


Syntax 
Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Defines a block of code for catching the first exception type thrown in a preceding 
TRY block. The exception-processing code can interrogate the exception object, if 
appropriate, to get more information about the specific cause of the exception. In- 
vocation of the THROW_LAST macro shifts processing to the next outer excep- 
tion frame. 


Note The CATCH block is defined as a C++ scope (delineated by curly braces). 
If you declare variables in this scope, remember that they are accessible only 
within that scope. 


If exception_class is CException, then all exception types will be caught. You can 
use CObject::IsKindOf to determine which specific exception was thrown. A bet- 
ter way to catch several kinds of exceptions is to use sequential AND. CATCH 
statements, each with a different exception type. 


Note The exception object is created by the macro. You do not need to declare it 
yourself. 


TRY, AND_CATCH, END_ CATCH, THROW, THROW_ LAST 


END_ CATCH Macro 


END_CATCH 
Marks the end of the last CATCH or AND_ CATCH block. 


TRY, CATCH, THROW, AND_ CATCH, THROW_LAST 


THROW Macro 


THROW( exception_object_pointer ); 


exception_object_pointer 
Points to an exception object derived from CException. 


Throws the specified exception. It interrupts program execution, passing control to 
the associated CATCH block in your program. If you have not provided the 


See Also 


Syntax 


Remarks 


See Also 


syntax 


Remarks 


See Also 
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CATCH block, then control is passed to a Microsoft Foundation Class Library 
module that prints an error message and exits. 


TRY, CATCH, THROW_LAST, AND_ CATCH, END_ CATCH 


THROW_ LAST Macro 


THROW_LASTO; 


Rethrows the exception back to the next outer CATCH block. If your code does 
not contain an outer block, then the Microsoft Foundation Class Library prints an 
appropriate error message and terminates the program, just as it would if you pro- 
vided no exception-processing logic. 


This allows you to throw a locally created exception. If you try to throw an excep- 
tion that you have just caught, it will normally go out of scope and be deleted. 
With THROW_LAST, the exception is passed correctly to the next CATCH 
handler. 


TRY, CATCH, THROW, AND_ CATCH, END_ CATCH 


TRY Macro 


TRY 


Identifies a block of code that might throw exceptions. Those exceptions are 
handled in the following CATCH and AND_ CATCH blocks. Recursion is al- 
lowed: exceptions may be passed to an outer TRY block, either by ignoring them 
or by using the THROW_LAST macro. 


Note The TRY block is defined as a C++ scope (delineated by curly braces). If 


you declare variables in this scope, remember that they are accessible only within 
that scope. 


THROW, CATCH, AND_ CATCH, END_ CATCH 


Message Map Cross-Reference 


This chapter lists all possible CWnd message map entries along with the corre- 
sponding member function prototypes. 


6.1 How to Use the Cross-Reference 


In entries where the term memberF xn is used, you must write your own member 
function for a derived CWnd class. You can give these functions any name you 
like. Other functions, such as OnActivate, are member functions of the CWnd 
base class that, if called, pass the message to the DefWindowProc Windows func- 
tion. If you wish to process Windows notification messages, you must override the 
corresponding CWnd function in your derived class. Your function should call the 
overridden function in your base class so that the base class(es), and Windows, 
can operate on the message. 


In all cases you must put the function prototype in the CWnd-derived class 
header, and you must code the message map entry as shown. See Chapter 14 of 
the Class Libraries User’s Guide cookbook for message map examples. 


The term id is any user-defined menu item ID (WM_COMMAND messages) or 
control ID (child window notification messages). The terms message and 
wNotifyCode are the Windows message IDs as defined in WINDOWS.H. The 
term nMessageVariable is the name of a variable that contains the return value 
from the RegisterWindowMessage Windows function. It must be declared 
NEAR. 
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6.2 Message Map Function Categories 


The rest of this section is divided into the following categories. Each category rep- 
resents a group of Windows messages for which the Microsoft Foundation Class 
Library provides handler functions that you can override in your derived window 
classes. 


= Handlers for WM_COMMAND messages generated by user menu selections 
= Handlers for WM_ COMMAND messages generated by keys 

= Handlers for notification messages from child windows 

= Handlers for WM_ messages, such as WM_ PAINT 


6.3 Handlers for WM_COMMAND Messages 


Map Entry Function Prototype 
ON_COMMAND( id, memberFxn ) afx_msg void memberFxn( ); 


6.4 Handlers for Child Window Notification Messages 
Generic Control Notification Codes 


Map Entry Function Prototype 
ON_CONTROL( wNotifyCode, id, memberFxn ) afx_ msg void memberFxn( ); 


User Button Notification Codes 


Map Entry ; Function Prototype 

ON_BN_CLICKED( id, memberFxn ) afx_msg void memberFxn( ); 
ON_BN_DISABLE( id, memberFxn ) afx_msg void memberFxn( ); 
ON_BN_ DOUBLECLICKED( id, memberFxn ) afx_msg void memberFxn( ); 
ON_BN_ HILITE( id, memberFxn ) afx_msg void memberFxn( ); 
ON_ BN_ PAINT( id, memberF xn ) afx_msg void memberFxn( ); 


ON_BN_UNHILITE( id, memberF xn ) afx_msg void memberFxn( ); 
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Combo Box Notification Codes 
Map Entry 


ON_CBN_DBLCLK( id, memberFxn ) 
ON_CBN_DROPDOWN( id, memberF xn ) 
ON_CBN_EDITCHANGE( id, memberF xn ) 
ON_CBN_EDITUPDATE( id, memberFxn ) 
ON_CBN_ERRSPACE( id, memberF xn ) 
ON_CBN_KILLFOCUS( id, memberFxn ) 
ON_CBN_SELCHANGE( id, memberFxn ) 


Function Prototype 


afx_msg void memberFxn( ); 
afx_msg void memberFxn( ); 
afx_msg void memberFxn( ); 
afx_ msg void memberFxn( ); 
afx_ msg void memberFxn( ); 
afx_ msg void memberFxn( ); 


afx_msg void memberFxn(); 


ON_CBN_SETFOCUS( id, memberFxn ) 


Edit Control Notification Codes 
Map Entry 


ON_EN_CHANGE( id, memberF xn ) 
ON_EN_ERRSPACE( id, memberFxn ) 
ON_EN_HSCROLL( id, memberFxn ) 
ON_EN_KILLFOCUS( id, memberFxn ) 
ON_EN_MAXTEXT( id, memberFxn ) 
ON_EN_SETFOCUS( id, memberFxn ) 
ON_EN_UPDATE( id, memberFxn ) 
ON_EN_VSCROLL( id, memberFxn ) 


List Box Notification Codes 
Map Entry 


ON_LBN_DBLCLK(C id, memberFxn ) 
ON_LBN_ERRSPACE( id, memberFxn ) 


ON_LBN_KILLFOCUS( id, memberFxn ) 
ON_LBN_SELCHANGE( id, memberFxn ) 


ON_LBN_SETFOCUS( id, memberFxn ) 


afx_msg void memberFxn( ); 


Function Prototype 


afx_msg void memberFxn( ); 
afx_msg void memberFxn( ); 
afx_msg void memberFxn( ); 
afx_msg void memberFxn( ); 
afx_msg void memberFxn( ); 
afx_msg void memberFxn( ); 
afx_msg void memberFxn( ); 


afx_msg void memberFxn( ); 


Function Prototype 


afx_msg void memberFxn( ); 
afx_ msg void memberFxn( ); 
afx_ msg void memberFxn( ); 
afx_msg void memberFxn( ); 


afx_ msg void memberFxn( ); 
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6.5 Handlers for Windows Notification Messages 


Map Entry 


ON_WM_ACTIVATE( ) 
ON_WM_ACTIVATEAPP( ) 
ON_WM_ASKCBFORMATNAME( ) 


ON_WM_CANCELMODE( ) 
ON_WM_CHANGECBCHAIN( ) 


ON_WM_CHAR() 
ON_WM_CHARTOITEM( ) 


ON_WM_CHILDACTIVATE( ) 
ON_WM_CLOSE( ) 
ON_WM_COMPACTING( ) 
ON_WM_COMPAREITEM( ) 


ON_WM_CREATE( ) 
ON_WM_CTLCOLOR( ) 


ON_WM_DEADCHAR( ) 
ON_WM_DELETEITEM( ) 


ON_WM_DESTROY( ) 
ON_WM_DESTROYCLIPBOARI( ) 
ON_WM_DEVMODECHANGK( ) 
ON_WM_DRAWCLIPBOARI( ) 
ON_WM_DRAWITEM( ) 


ON_WM_ENABLE( ) 
ON_WM_ENDSESSION( ) 
ON_WM_ENTERIDLK( ) 
ON_WM_ERASEBKGNI( ) 


Function Prototype 


afx_msg void OnActivate( UINT, CWnd*, BOOL ); 
afx_ msg void OnActivateApp( BOOL, HANDLE ); 


afx_msg void OnAskCbFormatName( UINT, 
LPSTR ); 


afx_msg void OnCancelMode( ); 


afx_msg void OnChangeCbChain( HWND, 
HWND ); 


afx_msg void OnChar( UINT, UINT, UINT ); 


afx_ msg int OnCharTolItem( UINT, CWnd*, 
UINT ); 


afx_msg void OnChildActivate( ); 
afx_msg void OnClose( ); 
afx_msg void OnCompacting( UINT ); 


afx_msg int 
OnCompareltem( LPCOMPAREITEMSTRUCT ); 


afx_msg int OnCreate( LPCREATESTRUCT ); 


afx_msg HBRUSH OnCtlColor( CDC*, CWnd*, 
UINT ); 


afx_msg void OnDeadChar( UINT, UINT, UINT ); 


afx_msg void OnDeleteItem 
(LPDELETEITEMSTRUCT ); 


afx_msg void OnDestroy(); 

afx_msg void OnDestroyClipboard( ); 
afx_msg void OnDevModeChange( LPSTR ); 
afx_msg void OnDrawClipboard( ); 


afx_msg void 
OnDrawlItem( LPDRAWITEMSTRUCT ); 


afx_msg void OnEnable( BOOL ); 

afx_msg void OnEndSession( BOOL ); 
afx_msg void OnEnterldle( UINT, CWnd* ); 
afx_msg BOOL OnEraseBkgnd( CDC* ); 


Map Entry 
ON_WM_FONTCHANGE( ) 
ON_WM_GETDLGCODE( ) 
ON_WM_GETMINMAXINFO( ) 
ON_WM_HSCROLL( ) 


ON_ WM_HSCROLLCLIPBOARD( ) 


ON_WM_ICONERASEBKGND( ) 
ON_ WM_INITMENU( ) 
ON_WML_INITMENUPOPUP( ) 


ON_WM_KEYDOWN() 
ON_WM_KEYUP( ) 
ON_WM_KILLFOCUS( ) 
ON_WM_LBUTTONDBLCLK( ) 
ON_WM_LBUTTONDOWN( ) 
ON_WM_LBUTTONUP( ) 
ON_WM_MBUTTONDBLCLKC(C ) 
ON_WM_MBUTTONDOWN( ) 
ON_WM_MBUTTONUP( ) 
ON_WM_ MDIACTIVATE( ) 


ON_WM_MEASUREITEM( ) 


ON_WM_MENUCHAR( ) 


ON_WM_MENUSELECT( ) 


ON_WM_MOUSEACTIVATE( ) 


ON_WM_MOUSEMOVE( ) 
ON_WM_MOVE( ) 
ON_ WM_ NCACTIVATE( ) 


Message Map Cross-Reference 


Function Prototype 


afx_msg void OnFontChange( ); 

afx_msg UINT OnGetDlgCode( ); 

afx_msg void OnGetMinMaxInfo( LPPOINT ); 
afx_msg void OnHScroll( UINT, UINT, CWnd* ); 


afx_msg void OnHScrollClipboard( CWnd*, UINT, 
UINT ); 


afx_msg void OnIconEraseBkgnd( CDC* ); 
afx_msg void OnInitMenu( CMenu* ); 


afx_msg void OnInitMenuPopup( CMenu*, UINT, 
BOOL ); 


afx_msg void OnKeyDown( UINT, UINT, UINT ); 
afx_msg void OnKeyUp( UINT, UINT, UINT ); 
afx_msg void OnKillFocus( CWnd* ); 

afx_msg void OnLButtonDbIClk( UINT, CPoint ); 
afx_msg void OnLButtonDown( UINT, CPoint ); 
afx_msg void OnLButtonUp( UINT, CPoint ); 
afx_msg void OnMButtonDbIClk( UINT, CPoint ); 
afx_msg void OnMButtonDown( UINT, CPoint ); 
afx_msg void OnMButtonUp( UINT, CPoint ); 


afx_ msg void OnMDIActivate( BOOL, CWnd*, 
CWnd* ); 


afx_msg void 
OnMeasureltem( LPMEASUREITEMSTRUCT ); 


afx_ msg LONG OnMenuChar( UINT, UINT, 
CMenu* ); 


afx_msg void OnMenuSelect( UINT, UINT, 
HMENU ); 


afx_ msg int OnMouseActivate( CWnd*, UINT, 
UINT ); 


afx_msg void OnMouseMove( UINT, CPoint ); 
afx_msg void OnMove( int, int ); 
aix_msg BOOL OnNcActivate( BOOL ); 
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Map Entry 


ON_WM_NCCALCSIZE( ) 
ON_WM_NCCREATE( ) 


ON_WM_NCDESTROY() 
ON_WM_NCHITTEST( ) 
ON_WM_NCLBUTTONDBLCLK(C ) 


ON_WM_NCLBUTTONDOWN( ) 
ON_WM_NCLBUTTONUP( ) 
ON_WM_NCMBUTTONDBLCLK( ) 


ON_WM_NCMBUTTONDOWN( ) 
ON_WM_NCMBUTTONUL( ) 
ON_WM_NCMOUSEMOVE( ) 
ON_WM_NCPAINT( ) 
ON_WM_NCRBUTTONDBLCLK( ) 


ON_WM_NCRBUTTONDOWN( ) 
ON_WM_NCRBUTTONUP( ) 
ON_WM_PAINT( ) 

ON_WM_ PAINTCLIPBOARD( ) 


ON_WM_PAINTICON( ) 
ON_WM_PALETTECHANGED( ) 
ON_WM_PARENTNOTIFY( ) 
ON_WM_QUERYDRAGICON( ) 
ON_WM_QUERYENDSESSION( ) 
ON_WM_QUERYNEWPALETTE( ) 
ON_WM_QUERYOPEN( ) 


Function Prototype 


afx_msg void OnNcCalcSize( LPRECT ); 


afx_msg BOOL 
OnNcCreate( LPCREATESTRUCT ); 


afx_msg void OnNcDestroy(); 
afx_msg UINT OnNcHitTest( CPoint ); 


afx_msg void OnNcLButtonDbICIk( UINT, 
CPoint ); 


afx_msg void OnNcLButtonDown( UINT, CPoint ); 
afx_msg void OnNcLButtonUp( UINT, CPoint ); 


afx_msg void OnNcMButtonDbICIk( UINT, 
CPoint ); 


afx_msg void OnNcMButtonDown( UINT, CPoint ); 
afx_msg void OnNcMButtonUp( UINT, CPoint ); 
afx_msg void OnNcMouseMove( UINT, CPoint ); 
afx_msg void OnNcPaint( ); 


afx_msg void OnNcRButtonDb!IClk( UINT, 
CPoint ); 


afx_msg void OnNcRButtonDown( UINT, CPoint ); 
afx_msg void OnNcRButtonUp( UINT, CPoint ); 
afx_msg void OnPaint( ); 


afx_ msg void OnPaintClipboard( CWnd*, 
HANDLE ); 


afx_msg void OnPaintIcon( ); 

afx_msg void OnPaletteChanged( CWnd* ); 
afx_msg void OnParentNotify( UINT, LONG ); 
afx_msg HCURSOR OnQueryDragIcon( ); 
afx_ msg BOOL OnQueryEndSession( ); 
afx_msg BOOL OnQueryNewPalette( ); 
afx_msg BOOL OnQueryOpen( ); 


Map Entry 


ON_WM_RBUTTONDBLCLK(C ) 
ON_WM_RBUTTONDOWN( ) 
ON_WM_RBUTTONUP( ) 
ON_WM_RENDERALLFORMATS( ) 
ON_WM_RENDERFORMAT( ) 
ON_WM_SETCURSOR( ) 


ON_WM_SETFOCUS( ) 
ON_WM_SHOWWINDOW( ) 
ON_WML_SIZE( ) 
ON_WM_SIZECLIPBOARD( ) 


ON_WM_SPOOLERSTATUS( ) 
ON_WM_SYSCHAR() 
ON_WM_SYSCOLORCHANGE( ) 
ON_WM_SYSCOMMAND( ) 
ON_WM_SYSDEADCHAR( ) 


ON_WM_SYSKEYDOWN( ) 


ON_WM_SYSKEYUP( ) 
ON_WM_ TIMECHANGE( ) 
ON_WM_TIMER( ) 
ON_WM_VKEYTOITEM( ) 


ON_WM_ VSCROLLIC ) 
ON_WM_ VSCROLLCLIPBOARD( ) 


ON_WM_ WININICHANGE( ) 


Message Map Cross-Reference 


Function Prototype 


afx_msg void OnRButtonDbICIk( UINT, CPoint ); 
afx_msg void OnRButtonDown( UINT, CPoint ); 
afx_msg void OnRButtonUp( UINT, CPoint ); 
afx_msg void OnRenderAllFormats( ); 

afx_msg void OnRenderFormat( UINT ); 


afx_ msg BOOL OnSetCursor( CWnd*, 
UINT, UINT ); 


afx_ msg void OnSetFocus( CWnd* ); 
afx_msg void OnShowWindow( BOOL, UINT ); 
afx_msg void OnSize( UINT, int, int ); 


afx_ msg void OnSizeClipboard( CWnd*, 
HANDLE ); 


afx_msg void OnSpoolerStatus( UINT, UINT ); 
afx_msg void OnSysChar( UINT, UINT, UINT ); 
afx_msg void OnSysColorChange( ); 

afx_msg void OnSysCommand( UINT, LONG ); 


afx_ msg void OnSysDeadChar( UINT, UINT, 
UINT ); 


afx_msg void OnSysKeyDown( UINT, UINT, 
UINT ); 


afx_msg void OnSysKeyUp( UINT, UINT, UINT ); 
afx_msg void OnTimeChange( ); 
afx_msg void OnTimer( UINT ); 


afx_msg int OnVKeyToItem( UINT, CWnd*, 
UINT ); 


afx_msg void OnVScroll( UINT, UINT, CWnd* ); 


afx_msg void OnVScrollClipboard( CWnd*, UINT, 
UINT ); 


afx_msg void OnWinIniChange( LPSTR ); 
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6.6 User-Defined Message Codes 


Map Entry Function Prototype 
ON_MESSAGE( message, memberFxn) afx_msg LONG memberFxn( UINT, LONG ); 
ON_REGISTERED_ MESSAGE afx_ msg LONG memberFxn( UINT, LONG ); 


(nMessageVariable memberFxn ) 


For more about the DECLARE_MESSAGE_ MAP, 
BEGIN_ MESSAGE_ MAP, and END_ MESSAGE_ MAP macros, see help. 


Structures and Enumerated Values 
for Windows 


This chapter lists data structures used by the Microsoft Foundation Windows 
classes, as well as Clipboard and mouse enumerated values. 


7.1 Structures 


The following data structures are presented in alphabetical order. The structure 
definition is followed by a description of each field. 


COMPAREITEMSTRUCT 


typedef struct tagCOMPAREITEMSTRUCT { 
WORD CtlType; 
WORD CLiiD: 
HWND hwndItem; 
WORD itemID1; 
DWORD itemDatal; 
WORD itemID2; 
DWORD itemData2; 
} COMPAREITEMSTRUCT; 


The COMPAREITEMSTRUCT structure supplies the identifiers and 
application-supplied data for two items in a sorted owner-draw combo box or 
list box. 


Whenever an application adds a new item to an owner-draw combo or list box 
created with the CBS_SORT or LBS_SORT style, Windows sends the owner 

a WM_COMPAREITTEM message. Override OnCompareltem to compare the 
two items and return a value indicating which item sorts before the other. 
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Members CtlType 
Is ODT_LISTBOX (which specifies an owner-draw list box) or 
ODT_COMBOBOX (which specifies an owner-draw combo box). 


CtuID 
Is the control ID for the list box or combo box. 


hwndItem 
Is the window handle of the control. 


itemID1 
Is the index of the first item in the list box or combo box being compared. 


itemDatal 
Is application-supplied data for the first item being compared. This value was 
passed in the call that added the item to the combo or list box. 


itemID2 
Is the index of the second item in the list box or combo box being compared. 


itemData2 
Is application-supplied data for the second item being compared. This value 
was passed in the call that added the item to the combo or list box. 


CREATESTRUCT 


typedef struct tagCREATESTRUCT { 
LPSTR IpCreateParams; 
HANDLE hInstance; 
HANDLE hMenu; 
HWND hwndParent; 


int Cy; 
int CX: 
int y; 
int x 


LONG style; 

LPSTR lpszName; 

LPSTR ITpszClass; 

DWORD dwExStyle; 
} CREATESTRUCT; 


The CREATESTRUCT structure defines the parameters used to initialize a 


window. When a window is created, it receives a WM_CREATE message with a 
pointer to this structure. For more information, see CWnd::OnCreate. 
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Members IpCreateParams 
Points to data to be used for creating the window. 


hInstance 
Identifies the module-instance handle of the module that owns the new window. 


hMenu 
Identifies the menu to be used by the new window. 


hwndParent 
Identifies the window that owns the new window. This member is NULL if the 
new window is a top-level window. 


cy 
Specifies the height of the new window. 


cx 
Specifies the width of the new window. 


Specifies the y-coordinate of the upper-left corner of the new window. Coordi- 
nates are relative to the parent window if the new window is a child window. 
Otherwise, the coordinates are relative to the screen origin. 


Specifies the x-coordinate of the upper-left corner of the new window. Coordi- 
nates are relative to the parent window if the new window is a child window. 
Otherwise, the coordinates are relative to the screen origin. 


style 
Specifies the new window’s style. 


IpszName 
Points to a null-terminated string that specifies the new window’s name. 


IpszClass 
Points to a null-terminated string that specifies the new window’s Windows 
class name. 


dwExStyle 
Specifies extended style for the new window. 
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Members 


DELETEITEMSTRUCT 


typedef struct tagDELETEITEMSTRUCT { 
WORD CtlType 
WORD CtlID; 
WORD itemID; 
HWND hwndItem; 
DWORD itemData; 
} DELETEITEMSTRUCT; 


The DELETEITEMSTRUCT structure describes a deleted owner-draw list-box 
or combo-box item. When an item is removed from the list box or combo box, or 
when the list box or combo box is destroyed, Windows sends the 
WM_DELETEITEM message to the owner for each deleted item along with a 
pointer to this structure. For more information, see CWnd::OnDeletelItem. 


CtlType 
Contains ODT_LISTBOX (which specifies an owner-draw list box) or 
ODT_COMBOBOX (which specifies an owner-draw combo box). 


CtuiD 
Contains the control ID for the list box or combo box. 


itemID 
Contains the index of the item in the list box or combo box being removed. 


hwndItem 
Contains the window handle of the control. 


itemData 
Contains the owner-defined value that was assigned to this item when it was 
created. 7 


Members 
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DRAWITEMSTRUCT 


typedef struct tagDRAWITEMSTRUCT { 


WORD 
WORD 
WORD 
WORD 
WORD 
HWND 
HDC 
RECT 
DWORD 


CtlType; 
CTI ID: 
itemID; 
itemAction; 
itemState; 
hwndItem; 
hDC; 
rciItem; 
itemData; 


} DRAWITEMSTRUCT; 


The DRAWITEMSTRUCT structure provides information the owner needs to 
determine how to paint an owner-draw control. The owner of the owner-draw con- 
trol receives a pointer to this structure with a WM_DRAWITEM message. For 
more information, see CWnd::OnDrawltem. 


CtlType 
Is the control type. The values for control types are as follows: 
Value Meaning 
ODT_BUTTON Owner-draw button 
ODT_COMBOBOX = Owner-draw combo box 
ODT_LISTBOX Owner-draw list box 
ODT_MENU Owner-draw menu 

CtlID 
Is the control ID for a combo box, list box, or button. This member is not used 
for a menu. 

itemID 


Is the menu-item ID for a menu or the index of the item in a list box or combo 
box. For an empty list box or combo box, this member can be —1. This allows 
the application to draw only the focus rectangle at the coordinates specified by 
the rcItem member even though there are no items in the control. This indi- 
cates to the user whether the list box or combo box has input focus. The setting 
of the bits in the itemAction member determines whether the rectangle is to be 
drawn as though the list box or combo box has input focus. 
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itemAction 

Defines the drawing action required. This will be one or more of the fol- 

lowing bits: 

Value Meaning 

ODA_DRAWENTIRE __ This bit is set when the entire control needs to 
be drawn. 

ODA_FOCUS This bit is set when the control gains or loses 
input focus. The itemState member should be 
checked to determine whether the control has 
focus. 

ODA_SELECT This bit is set when only the selection status has 
changed. The itemState member should be 
checked to determine the new selection state. 

itemState 


Specifies the visual state of the item after the current drawing action takes 
place. That is, if a menu item is to be dimmed, the state flag ODS_GRAYED 
will be set. The state flags are as follows: 


Value Meaning 


ODS_CHECKED This bit is set if the menu item is to be checked. 
This bit is used only in a menu. | 


ODS_DISABLFD This bit is set if the item 1s to be drawn as disabled. 
ODS_FOCUS This bit is set if the item has input focus. 


ODS_GRAYED This bit is set if the item is to be dimmed. This bit 
is used only in a menu. 


ODS_ SELECTED This bit is set if the item’s status is selected. 


hwndItem 
Specifies the window handle of the control for combo boxes, list boxes, and but- 
tons. It contains the handle of the menu (HMENU) containing the item for 
menus. 


hDC 
Identifies a device context. This device context must be used when performing 
drawing operations on the control. 


rcltem 
Is a rectangle in the device context specified by the hDC member that defines 
the boundaries of the control to be drawn. Windows automatically clips any- 
thing the owner draws in the device context for combo boxes, list boxes, and 
buttons, but does not clip menu items. When drawing menu items, the owner 


Members 
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must ensure that the owner does not draw outside the boundaries of the rec- 
tangle defined by the rcItem member. 


itemData 
Contains the owner-defined value that was assigned to this item when it was 
created. 


MEASUREITEMSTRUCT 


typedef struct tagMEASUREITEMSTRUCT { 
WORD CtlType; 
WORD Ctlib; 
WORD itemID; 
WORD itemWidth; 
WORD itemHeight; 
DWORD itemData 
+} MEASUREITEMSTRUCT ; 


When an owner-draw control is created, Windows sends the 
WM_MEASUREITEM message to the owner of the control, along with a 
pointer to a MEASUREITEMSTRUCT data structure. 


The MEASUREITEMSTRUCT data structure must be filled in order for 
Windows to process user interaction with the control correctly. For more informa- 
tion, see CWnd::OnMeasureltem. 


The MEASUREITEMSTRUCT data structure informs Windows of the dimen- 
sions of an owner-draw control. This allows Windows to correctly process user in- 
teraction with the control. The owner of an owner-draw control receives a pointer 
to this structure as the /Param parameter of an WM_MEASUREITEM message. 
The owner-draw control sends this message to its owner window when the control 
is created. The owner then fills in the appropriate members in the structure for the 
control and returns. This structure is common to all owner-draw controls. 


CtlType 
Is the control type. The values for control types are as follows: 
Value Meaning 
ODT_BUTTON Owner-draw button 
ODT_COMBOBOX = Owner-draw combo box 
ODT_LISTBOX Owner-draw list box 


ODT_MENU Owner-draw menu 
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Remarks 


CtlID 
Is the control ID for a combo box, list box, or button. This member is not used 
for a menu. 


itemID 
Is the menu-item ID for a menu or the list-box item ID for a variable-height 
combo box or list box. This member is not used for a fixed-height combo box 
or list box, or for a button. 


item Width 
Specifies the width of a menu item. The owner of the owner-draw menu item 
must fill this member before returning from the message. 


itemHeight 
Specifies the height of an individual item in a list box or a menu. Before return- 
ing from the message, the owner of the owner-draw combo box, list box, or 
menu item must fill out this member. The maximum height of a list box item 
is 255. 


itemData 
Contains the owner-defined value that was assigned to this item when it was 
created. 


Failure to assign values to item Width and itemHeight members in the 
MEASUREITEMSTRUCT structure will cause improper operation of the 
control. 


PAINTSTRUCT 


typedef struct tagPAINTSTRUCT { 
HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[16]; 
} PAINTSTRUCT; 


The PAINTSTRUCT structure contains information that can be used to paint the 
client area of a window. 


Members 


Members 
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hdc 
Identifies the display context to be used for painting. 


fErase 
Specifies whether the background needs to be redrawn. It is not zero if the appli- 
cation should redraw the background. The application is responsible for draw- 
ing the background if a Windows window class is created without a 
background brush (see the description of the hbrBackground member of the 
WNDCLASS structure). 


rcPaint 
Specifies the upper-left and lower-right corners of the rectangle in which the 
painting is requested. 


fRestore 
Reserved member. It is used internally by Windows. 


fIncUpdate 
Reserved member. It is used internally by Windows. 


rgbReserved[16] 
Reserved member. A reserved block of memory used internally by Windows. 


POINT 


typedef struct tagPOINT { 
int x; 
TAL SYS 

} POINT; 


The POINT structure defines the x- and y-coordinates of a point. 


Xx 
Specifies the x-coordinate of a point. 


Specifies the y-coordinate of a point. 


86 The Class Libraries Reference 


Members 


Remarks 


RECT 


typedef struct tagRECT { 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


The RECT structure defines the coordinates of the upper-left and lower-right 
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left 
Specifies the x-coordinate of the upper-left corner of a rectangle. 


top 

Specifies the y-coordinate of the upper-left corner of a rectangle. 
right 

Specifies the x-coordinate of the lower-right corner of a rectangle. 


bottom 
Specifies the y-coordinate of the lower-right corner of a rectangle. 


Neither the width nor height of the rectangle defined by the RECT structure can 
exceed 32,767 units. 


7.2 Clipboard Enumerated Values 


The following list shows the enumerated values that specify system-defined 
Clipboard formats: 


Value Meaning 
CF_BITMAP The data is a bitmap. 
CF_DIB The data is a memory block containing a 


BITMAPINFO structure followed by the 
bitmap data. 


CF_DIF The data is in Data Interchange Format 
(Software Arts). 


Value 


CF_DSPBITMAP 


CF_DSPMETAFILEPICT 


CF_DSPTEXT 


CF_METAFILEPICT 


CF_OEMTEXT 


CF_OWNERDISPLAY 


_CF_PALETTE 
CF_SYLK 


CF_TEXT 


CF_TIFF 
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Meaning 


The data is a bitmap representation of a private 
format. This data is displayed in bitmap format 
in lieu of the privately formatted data. 


The data is a metafile representation of a private 
data format. This data is displayed in metafile- 
picture format in lieu of the privately formatted 
data. 


The data is a textual representation of a private 
data format. This data is displayed in text 
format in lieu of the privately formatted data. 


The data is a metafile (for more information, 
see description of METAFILEPICT structure). 


The data is an array of text characters in the 
OEM character set. Each line ends with a 
carriage return—linefeed combination. A null 
character signals the end of the data. 


The data is in a private format that the 
Clipboard owner must display. 


The data is a color palette. 


The data is in Microsoft Symbolic Link 
(SYLK) format. 


The data is an array of text characters. Each line 
ends with a carriage return—linefeed 
combination. A null character signals the end of 
the data. 


The data is in Tag Image File Format. 


Private data formats in the range of CF_PRIVATEFIRST to 
CF_PRIVATELAST are not automatically freed when the data is deleted from 
the Clipboard. Data handles associated with these formats should be freed upon re- 
ceiving aWM_DESTROYCLIPBOARD message. 


Private data formats in the range of CF_GDIOBJFIRST to CF_GDIOBJLAST 
will be automatically deleted with a call to CGdiObject::DeleteObject when the 
data is deleted from the Clipboard. 
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7.3 Mouse Enumerated Values 


The following enumerated values are passed to the CWnd::OnMessage member 
functions that handle mouse messages, such as CWnd::OnMouseActivate and 
CWnd::OnNcLButtonDDbICIk. 


Value 


HTBOTTOM 


HTBOTTOMLEFT 
HTBOTTOMRIGHT 


HTCAPTION 
HTCLIENT 
HTERROR 


HTGROWBOX 
HTHSCROLL 
HTLEFT 
HTMENU 
HTNOWHERE 


HTREDUCE 
HTRIGHT 
HTSIZE 
HTSYSMENU 


HTTOP 
HTTOPLEFT 
HTTOPRIGHT 


HTTRANSPARENT 


HTVSCROLL 
HTZOOM 


Meaning 


In the lower-horizontal border of the window. 
In the lower-left corner of the window border. 
In the lower-right corner of the window border. 
In a caption area. | 

In a client area. 


Same as HTNOWHERE except that default 
message processing produces a system beep to 
indicate an error. 


In a size box. 

In the horizontal scroll bar. 

In the left border of the window. 
In a menu area. 


On the screen background or on a dividing line 
between the windows. 


In a Minimize box. 
In the right border of the window. 
Same as HTGROWBOX. 


In a control-menu box (close box in child 
windows). 


In the upper-horizontal border of the window. 
In the upper-left corner of the window border. 


In the upper-right corner of the window border. 


In a window currently covered by another window. 


In the vertical scroll bar. 


In a Maximize box. 
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class CArchive 


See Also 


Preconditions 


Public Members 


The CArchive class allows you to save a complex network of objects in a perma- 
nent binary form (usually disk storage) that “persists” after those objects are de- 
leted. Later you can load the objects from persistent storage, “reconstituting” them 
in memory. This process of making data persistent is called “serialization.” 


You can think of an archive object as a kind of binary stream. Like an input/output 
stream, an archive is associated with a file and permits the buffered writing and 
reading of data to and from storage. An input/output stream processes sequences 
of ASCII characters, but an archive processes binary object data in an efficient, 
nonredundant format. 


When you construct a CArchive object, you attach it to an object of class CFile 
(or a derived class) that represents an open file. You also specify whether the ar- 
chive will be used for loading or storing. A CArchive object can process not only 
primitive types but also objects of CObject-derived classes designed for serializa- 
tion. A serializable class must have a Serialize member function, and it must use 
the DECLARE_SERIAL and IMPLEMENT_SERIAL macros, as described 
under class CObject. 


The overloaded extraction (>>) and insertion (<<) operators are convenient ar- 
chive programming interfaces that support both primitive types and CObject- 
derived classes. 


#include <afx.h> 
CFile, CObject 


You must create a CFile object before you can create a CArchive object. In addi- 
tion, you must ensure that the archive’s load/store status is compatible with the 
file’s open mode. You are limited to one active archive per file. 


Construction/Destruction 


CArchive Creates a CArchive object. 

~CArchive Destroys a CArchive object and flushes unwritten 
data. 

Close Flushes unwritten data and disconnects from the 


CFile. 
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CArchive 


Basic Input/Output 
Flush 

operator << 
operator >> 

Read 

Write 


Status 
GetFile 
IsLoading 
IsStoring 


Protected Members 


Object Input/Output 
ReadObject 
WriteObject 


Flushes unwritten data from the archive buffer. 
Stores objects and primitive types to the archive. 
Loads objects and primitive types from the archive. 
Reads raw bytes. 


Writes raw bytes. 


Gets the CFile object pointer for this archive. 
Determines if the archive is loading. 


Determines if the archive is storing. 


Calls an object’s Serialize function for loading. 


Calls an object’s Serialize function for storing. 
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Member Functions 


Syntax 


Parameters 


Remarks 


CArchive::CArchive 


CArchive( CFile* pFile, UINT nMode, int nBufSize = 512, 
void FAR* /pBuf = NULL ) 
throw( CMemoryException, CArchiveException, CFileException ); 


pFile 
A pointer to the CFile object that is the ultimate source or destination of the per- 
sistent data. 


nMode 
A flag that specifies whether objects will be loaded from or stored to the ar- 
chive. The nMode parameter must have one of the following values: 


Value Meaning 
CArchive::load Load data from the archive. Requires only CFile read 
permission. 
CArchive::store Save data to the archive. Requires CFile write 
permission. 
nBufSize 


An integer that specifies the size of the internal file buffer, in bytes. 


Note The default buffer size is 512 bytes. If you routinely archive large objects, 
you will improve performance if you use a larger buffer size that is a multiple 
of the file buffer size. 


lpBuf 
An optional FAR pointer to a user-supplied buffer of size nBufSize. If you do 
not specify this parameter, the archive allocates a buffer from the local heap 
and frees it when the object is destroyed. The archive does not free a user- 
supplied buffer. 


Constructs a CArchive object and specifies whether it will be used for loading or 
storing objects. You cannot change this specification after you have created the 
archive. 
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Example 


See Also 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


You may not use CFile operations to alter the state of the file until you have 
closed the archive. Any such operation will damage the integrity of the archive. 
You may access the position of the file pointer at any time during serialization by 
(1) obtaining the archive’s file object from the GetFile member function and then 
(2) using the CFile::GetPosition function. You should call CArchive::Flush 
before obtaining the position of the file pointer. 


extern char* pFileName; 
CFile 3 
char buf[{512]; 
if( !f.Open( pFileName, CFile::modeCreate | CFile::modeWrite ) ) { 
#ifdef _ DEBUG 
afxDump << "Unable to open file" << "\\n"; 
exit( 1 ); 
#Fendif 
} 
CArchive ar( &f, CArchive::store, 512, buf ); 


CArchive::Close, CArchive::Flush, CFile::Close 


CArchive::~CArchive 


~CArchive(); 


The CArchive destructor closes the archive if it is not closed already. However, 
you should call the member function Close before calling the destructor. After you 
have used the CFile object for archiving, you must close and destroy it as you usu- 
ally would. 


CArchive::Flush, CFile::Close 


CArchive::Close 


void Close() 
throw( CArchiveException, CFileException ); 


Flushes any data remaining in the buffer, closes the archive, and disconnects the 
archive from the file. No further operations on the archive are permitted. After you 
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close an archive, you can create another archive for the same file or you can close 
the file. 


The member function Close ensures that all data is transferred from the archive to 
the file, and it makes the archive unavailable. To complete the transfer from the 


file to the storage medium, you must first use CFile::Close and then destroy the 
CFile object. 


See Also CArchive::Flush 


CArchive::Flush 


Syntax void Flush() 
throw( CFileException ); 


Remarks Forces any data remaining in the archive buffer to be written to the file. 
The member function Flush ensures that all data is transferred from the archive to 


the file. You must call CFile::Close to complete the transfer from the file to the 
storage medium. 


See Also CArchive::Close, CFile::Flush, CFile::Close 


CArchive::GetFile 


Syntax CFile* GetFile() const; 

Remarks Gets the CFile object pointer for this archive. You must flush the archive before 
using GetFile. 

Return Value A constant pointer to the CFile object in use. 

Example extern CArchive ar; 


const CFile* fp = ar.GetFile(); 
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Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


Example 


See Also 


CArchive::lsLoading 
BOOL IsLoading() const; 


Determines if the archive is loading data. This member function is called by the 
Serialize functions of the archived classes. 


TRUE if the archive is currently being used for loading; otherwise FALSE. 


int 1; 
extern CArchive ar; 
if( ar.IsLoading() ) 
ar >> 1; 
else 
ar << 713 


CArchive::IsStoring 


CArchive::IsStoring 
BOOL IsStoring() const; 


Determines if the archive is storing data. This member function is called by the 
Serialize functions of the archived classes. 


If the IsStoring status of an archive is TRUE, then its IsLoading status is 
FALSE, and vice versa. 


TRUE if the archive is currently being used for storing; otherwise FALSE. 


int 1; 
extern CArchive ar; 
if( ar.IsStoring() ) 
ar << 1; 
else 
ar >> 13 


CArchive::IsLoading 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


Syntax 


Parameters 


Remarks 


CArchive::ReadObject 9 


CArchive::Read 


UINT Read( void FAR* /pBuf, UINT nMax ) 
throw( CFileException ); 


lpBuf 
A FAR pointer to a user-supplied buffer that is to receive the data read from the 
archive. 


nMax 
An unsigned integer specifying the number of bytes to be read from the archive. 


Reads a specified number of bytes from the archive. The archive does not interpret 
the bytes. 


You can use the Read member function within your Serialize function for reading 
ordinary structures that are contained in your objects. 


An unsigned integer containing the number of bytes actually read. If the return 
value is less than the number requested, the end of file has been reached. No excep- 
tion is thrown on the end-of-file condition. 


extern CArchive ar; 
char pbL100]; 
UINT nr = ar.Read( pb, 100 ); 


CArchive::ReadObject 


Protected: 
CObject* ReadObject( const CRuntimeClass* pClass ) 
throw( CFileException, CArchiveException, CMemoryException ); 


pClass 
A constant pointer to the CRuntimeClass structure that corresponds to the ob- 
ject that you expect to read. 


Reads object data from the archive and constructs an object of the appropriate 
type. If the object contains pointers to other objects, those objects are constructed 
automatically. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Example 


See Also 


This protected function is usually called by the public CArchive extraction (>>) 
operator, overloaded for a CObject pointer. ReadObject, in turn, calls the 
Serialize function of the archived class. 


If you supply a nonzero pClass parameter, which is obtained by the 

RUNTIME_ CLASS macro, then the function verifies the run-time class of the ar- 
chived object. This assumes you have used the IMPLEMENT_SERIAL macro 
in the implementation of the class. 


A CObject pointer that must be safely cast to the correct derived class by using 
CObject::IsKindOf. 


CArchive::WriteObject, CObject::IsKindOf 


CArchive::Write 


void Write( const void FAR* [pBuf, UINT nMax ) 
throw( CFileException ); 


[pBuf 
A pointer to a user-supplied buffer that contains the data to be written to the 
_ archive. 


nMax 
An integer that specifies the number of bytes to be written to the archive. 


Writes a specified number of bytes to the archive. The archive does not format the 
bytes. 


You can use the Write member function within your Serialize function to write or- 
dinary structures that are contained in your objects. 


extern CArchive ar; 
char pb[l10@]; 
ar.Write( pb, 100 ); 


CArchive::Read 


Syntax 


Parameters 


Remarks 


See Also 
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CArchive::WriteObject 


Protected: 
void WriteObject( const CObject* pOb ) 
throw( CFileException, CArchiveException ); 


pOb 
A constant pointer to the object being stored. 


Stores the specified CObject to the archive. If the object contains pointers to other 
objects, they are serialized in turn. 


This protected function is normally called by the public CArchive insertion (<<) 
operator, overloaded for CObject. WriteObject, in turn, calls the Serialize func- 
tion of the archived class. 


You must use the IMPLEMENT_SERIAL macro to enable archiving. 
WriteObject writes the ASCII class name to the archive. This class name is vali- 
dated later during the load process. A special encoding scheme prevents unneces- 
sary duplication of the class name for multiple objects of the class. This scheme 
also prevents redundant storage of objects that are targets of more than one pointer. 


The exact object encoding method (including the presence of the ASCII class 
name) is an implementation detail and could change in future versions of the 
library. 


Note Finish creating, deleting, and updating all your objects before you begin to 


archive them. Your archive will be corrupted if you mix archiving with object 
modification. 


CArchive::ReadObject 
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Operators 


Syntax 


Remarks 


Return Value 


Example 


See Also 


CArchive::operator >> 


friend CArchive& operator >>( CArchive &ar, CObject *& pOb ) 
throw( CArchiveException, CFileException, CMemoryException ); 


friend CArchive& operator >>( CArchive& ar, const CObject *& pOb ) 
throw( CArchiveExcention, CFileExcention, CMemoryExcention ); 
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CArchive& operator >>( BYTE& by ) 
throw( CArchiveException, CFileException ); 


CArchive& operator >>( WORD& w ) 
throw( CArchiveException, CFileException ); 


CArchive& operator >>( LONG& | ) 
throw( CArchiveException, CFileException ); 


CArchive& operator >>( DWORD& dw ) 
throw( CArchiveException, CFileException ); 


Loads the indicated object or primitive type from the archive. 


If you used the IMPLEMENT_SERIAL macro in your class implementation, 
then the extraction operators overloaded for CObject call the protected 
ReadObject function (with a nonzero run-time class pointer). This function, in 
turn, calls the Serialize function of the class. 


A CArchive reference that enables multiple insertion operators on a single line. 
int 1; 
extern CArchive ar; 


if( ar.IsLoading() ) 
ar >> 1; 


CArchive::ReadObject, CObject::Serialize 


Syntax 


Remarks 


Return Value 


Example 


See Also 
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CArchive::operator << 


friend CArchive& operator <<( CArchive& ar, const CObject* pOb ) 
throw( CArchiveException, CFileException ); 


CArchive& operator <<( BYTE by ) 
throw( CArchiveException, CFileException ); 


CArchive& operator <<( WORD w ) 
throw( CArchiveException, CFileException ); 


CArchive& operator <<( LONG / ) 
throw( CArchiveException, CFileException ); 


CArchive& operator <<( DWORD dw ) 
throw( CArchiveException, CFileException ); 


Stores the indicated object or primitive type to the archive. 


If you used the IMPLEMENT_SERIAL macro in your class implementation, 
then the insertion operator overloaded for CObject calls the protected 
WriteObject. This function, in turn, calls the Serialize function of the class. 


A CArchive reference that enables multiple insertion operators on a single line. 


long 1; 

TOG. 13 

extern CArchive ar; 

if( ar.IsStoring() ) 
ar >> | >> 713 


CArchive::WriteObject, CObject::Serialize 


104 = CArchiveException 


class CArchiveException : public CException 


A CArchiveException object represents a 
serialization exception condition. The 
CArchiveException class includes a public data 
member that indicates the cause of the exception. 


#include <afx.h> 
See Also CArchive, AfxThrowArchiveException, Chapter 5, “Exception Processing” 


Comments CArchiveException objects are constructed and thrown inside CArchive member 
functions. You can access these objects within the scope of a CATCH expression. 
The cause code is independent of the operating system. 


Public Members 


Data Members 


m_ cause Indicates the exception cause. 


Construction/Destruction 
CArchiveException Constructs a CArchiveException object. 
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Member Functions 


CArchiveException::CArchiveException 


Syntax CArchiveException( int cause = CArchiveException::none ); 


Parameters cause 
An enumerated type variable that indicates the reason for the exception. See the 
m_cause data member for a list of the enumerators. 


Remarks Constructs a CArchiveException object, storing the cause code in the object. You 
can create a CArchiveException object on the heap and throw it yourself or let 
AfxThrowArchiveException handle it for you. 


Do not use this constructor directly, but call the global function 
AfxThrowArchiveException. 
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CArchiveException::m_cause 


Data Members 


Syntax 


Remarks 


Example 


CArchiveException::m_cause 


int m_cause; 


Specifies the cause of the exception. Its values are defined by a 
CArchiveException enumerated type. The enumerators are: 


Value Meaning 
CArchiveException::none No error occurred. 
CArchiveException::generic Unspecified error. 
CArchiveException::readOnly Tried to write into an archive opened for 
| loading. 
CArchiveException::endOfFile Reached end of file while reading an 
object. 
CArchiveException::writeOnly Tried to read from an archive opened for 
storing. 
CArchiveException::badIndex Invalid file format. 
CArchiveException::badClass Tried to read an object into an object of 


the wrong type. 


CArchiveException::badSchema __ Tried to read an object with a different 
version of the class. 7 


Note These CArchiveException cause enumerators are distinct from the 
CFileException cause enumerators. 


extern CFile f; Be 
TRY 
{ 

CArchive ar( &f, CArchive::store ); 
} 
CATCH( CArchiveException, e) 
{ 

if( e->m_cause == CArchiveException::readOnly ) 

printf( "ERROR: Archive is read-only\\n" ); 

} 


END CATCH 


Public Members 


The CBitmap class encapsulates a Windows graphical 
design interface (GDI) bitmap and provides member 
functions to manipulate the bitmap. To use a CBitmap 
object, construct the object, install a bitmap handle in 
it with one of the initialization member functions, and 
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class CBitmap : public CGdiObject 


CObject | 
E 

. . e 
CGdiObject 
: 

Bitmap / 
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then call the object’s member functions. 


Construction/Destruction 


CBitmap 


Initialization 
LoadBitmap 


LoadOEMBitmap 


CreateBitmap 


CreateBitmapIndirect 


CreateCompatibleBitmap 


CreateDiscardableBitmap 


Operations 
FromHandle 


SetBitmapBits 
GetBitmapBits 


Constructs a CBitmap object. 


Initializes the object by loading a named bitmap re- 
source from the application’s executable file and 
attaching the bitmap to the object. 


Initializes the object by loading a predefined 
Windows bitmap and attaching the bitmap to the 
object. 


Initializes the object with a device-dependent 
memory bitmap with a specified width, height, and 
bit pattern. 


Initializes the object with a bitmap that has the 
width, height, and bit pattern (if one is specified) 
given in a BITMAP structure. 

Initializes the object with a bitmap so that it is com- 
patible with a specified device. 


Initializes the object with a discardable bitmap that 
is compatible with a specified device. 


Returns a pointer to a CBitmap object when given 
a handle to a Windows HBITMAP bitmap. 


Sets the bits of a bitmap to the specified bit values. 


Copies the bits of the specified bitmap into the 
specified buffer. 
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CBitmap 


SetBitmapDimension 


GetBitmapDimension 


Assigns a width and height to a bitmap in 
0.1-millimeter units. 


Returns the width and height of the bitmap. The 
height and width are assumed to have been set pre- 
viously by the SetBitmapDimension member 
function. 
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Member Functions 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CBitmap::CBitmap 
CBitmap(); 


Constructs a CBitmap object. The resulting object must be initialized with one of 
the initialization member functions. 


CBitmap::LoadBitmap, CBitmap::LoadOEMBitmap, 
CBitmap::CreateBitmap, CBitmap::CreateBitmapIndirect, 
CBitmap::CreateCompatibleBitmap, CBitmap::CreateDiscardableBitmap 


CBitmap::CreateBitmap 


BOOL CreateBitmap( int nWidth, int nHeight, BYTE nPlanes, 
BYTE nBitcount, LPSTR [pBits ); 


nWidth 
Specifies the width (in pixels) of the bitmap. 


nHeight 
Specifies the height (in pixels) of the bitmap. 


nPlanes 
Specifies the number of color planes in the bitmap. 


nbitcount 
Specifies the number of color bits per display pixel. 


[pBits 
Points to a short-integer array that contains the initial bitmap bit values. If it is 
NULL, the new bitmap is left uninitialized. For more information, see the de- 
scription of the bmBits field in the BITMAP structure in the Windows Soft- 
ware Development Kit documentation. 


Initializes a device-dependent memory bitmap that has the specified width, height, 
and bit pattern. Although a bitmap cannot be directly selected for a display device, 
it can be selected as the current bitmap for a memory device context by using 
CDC::SelectObject or CMetaFileDC::SelectObject and copied to any compat- 
ible device context by using the CDC::BitBlt function. When an application has 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


':CreateBitmapindirect 


finished using the bitmap created by the CreateBitmap function, it should select 
the bitmap out of the device context. 


TRUE if successful; otherwise FALSE. 


CDC::SelectObject, CMetaFileDC::SelectObject, CDC::BitBlt, 
::CreateBitmap 


CBitmap::CreateBitmaplndirect 


BOOL CreateBitmapIndirect( LPBITMAP [pBitmap ); 


| lpBitmap 


Points to a BITMAP structure that contains information about the bitmap. 
The BITMAP structure has the following form: 


typedef struct tagBITMAP { 
int bmType; 
int bmWidth; 
THE bmHeight; 
int bmWidthBytes; 
BYTE bmPlanes; 
BYTE bmBitsPixel; 
LPSTR  bmBits; 

} BITMAP; 


Initializes a bitmap that has the width, height, and bit pattern (if one is specified) 
given in the structure pointed to by /pBitmap. Although a bitmap cannot be 
directly selected for a display device, it can be selected as the current bitmap for 
a memory device context by using CDC::SelectObject, or 
CMetaFileDC::SelectObject and copied to any compatible device context by 
using the CDC:: BitBlt function. 


When an application has finished using the bitmap initialized by 
CreateBitmapIndirect, it should select the bitmap out of the device context. 


TRUE if successful; otherwise FALSE. 


CDC::SelectObject, CMetaFileDC::SelectObject, CDC::BitBlt, 
::CreateBitmapIndirect 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CBitmap::CreateCompatibleBitmap 
BOOL CreateCompatibleBitmap( CDC* pDC, int nWidth, int nHeight ); 


pDC 
Specifies the device context. 


nWidth 
Specifies the width (in bits) of the bitmap. 


nHeight 
Specifies the height (in bits) of the bitmap. 


Initializes a bitmap that is compatible with the device specified by pDC. The bit- 

map has the same number of color planes or the same bits-per-pixel format as the 
specified device context. It can be selected as the current bitmap for any memory 
device that is compatible with the one specified by pDC. 


If pDC is amemory device context, the bitmap returned has the same format as 
the currently selected bitmap in that device context. A “memory device context” 
is a block of memory that represents a display surface. It can be used to prepare 
images in memory before copying them to the actual display surface of the com- 
patible device. 


When a memory device context is created, GDI automatically selects a mono- 
chrome stock bitmap for it. 


Since a color memory device context can have either color or monochrome 
bitmaps selected, the format of the bitmap returned by the 
CreateCompatibleBitmap function is not always the same; however, the 
format of a compatible bitmap for a nonmemory device context is always 
in the format of the device. 


When you are finished with a CBitmap initialized with 


CreateCompatibleBitmap, you must select the bitmap out of the device 
context. 


TRUE if successful; otherwise FALSE. 


::CreateCompatibleBitmap 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CBitmap::CreateDiscardableBitmap 


BOOL CreateDiscardableBitmap( CDC* pDC, int nWidth, int nHeight ); 


pDC 
Specifies a device context. 


nWidth 
Specifies the width (in bits) of the bitmap. 


nHeight 


aaw 


Specifies the height (in bits) of the bitmap. 


Initializes a discardable bitmap that is compatible with the device context iden- 
tified by pDC. The bitmap has the same number of color planes or the same bits- 
per-pixel format as the specified device context. An application can select this 
bitmap as the current bitmap for a memory device that is compatible with the one 
specified by pDC. 


Windows can discard a bitmap created by this function only if an application 

has not selected it into a display context. If Windows discards the bitmap 

when it is not selected and the application later attempts to select it, the 

CDC: :SelectObject or CMetaFileDC::SelectObject function will return NULL. 


When an application has finished using the bitmap created by the 
CreateBitmapIndirect function, it should select the bitmap out of the device 
context. 

TRUE if successful; otherwise FALSE. 


::CreateDiscardableBitmap 
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CBitmap::FromHandle 
Syntax static CBitmap* FromHandle( HBITMAP hBitmap ); 


Parameters hBitmap 
Specifies a Windows GDI bitmap. 


Remarks Returns a pointer to a CBitmap object when given a handle to a Windows GDI 
bitmap. If a CBitmap object is not already attached to the handle, a temporary 
CBitmap object is created and attached. This temporary CBitmap object is valid 
only until the next time the application has idle time in its event loop, at which 
time all temporary graphic objects are deleted. Another way of saying this is that 
the temporary object is only valid during the processing of one window message. 


Return Value A pointer to a CBitmap object if successful; otherwise NULL. 


CBitmap::GetBitmapBits 


Syntax DWORD GetBitmapBits( DWORD dwCount, LPSTR I[pBits ) const; 
Parameters dwCount 
Specifies the number of bytes to be copied. 
[pBits 


Points to the buffer that is to receive the bitmap. The bitmap is an array of 
bytes. The bitmap byte array conforms to a structure where horizontal scan 
lines are multiples of 16 bits. 


Remarks Copies the bit pattern of the CBitmap object into the buffer that is pointed to by 
[pBits. The dwCount parameter specifies the number of bytes to be copied to the 
buffer. Use GetObject to determine the correct dwCount value for the given 
bitmap. 

Return Value The actual number of bytes in the bitmap, or 0 if there is an error. 


See Also CGdiObject::GetObject, ::GetBitmapBits 
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syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


‘GetBitmapDimension 


CBitmap::GetBitmapDimension 
CSize GetBitmapDimension() const; 


Returns the width and height of the bitmap. The height and width are assumed to 
have been set previously by using the SetBitmapDimension function. 


The width and height of the bitmap, measured in 0.1-millimeter units. The height 
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CBitmap::SetBitmapDimension, ::GetBitmapDimension 


CBitmap::LoadBitmap 


BOOL LoadBitmap( const char FAR* [pBitmapName ); 
BOOL LoadBitmap( UINT n/DBitmap ); 


[pBitmapName 
Points to a null-terminated string that contains the name of the bitmap resource. 


nlDBitmap 
Specifies the resource ID number of the bitmap resource. 


Loads the bitmap resource named by /pBitmapName or identified by the [ID num- 
ber in n/DBitmap from the application’s executable file. The loaded bitmap is at- 
tached to the CBitmap object. 


If the bitmap identified by JpBitmapName does not exist or if there is insufficient 
memory to load the bitmap, the function returns FALSE. 


TRUE if successful; otherwise FALSE. 


CBitmap::LoadOEMBitmap, ::LoadBitmap 
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CBitmap::LoadOEMBitmap 


Syntax BOOL LoadOEMBitmap( UINT n/DBitmap ); 


Parameters nIDBitmap 


ID number of the predefined Windows bitmap. The possible values are listed 
below from WINDOWS.H: 


OBM_BTNCORNERS 
OBM_ BTSIZE 
OBM_CHECK 
OBM_CHECKBOXES 
OBM_ CLOSE 
OBM_COMBO 
OBM_DNARROW 
OBM_DNARROWD 
OBM_DNARROWI 
OBM_LFARROW 
OBM_LFARROWD 
OBM_LFARROWI 
OBM_MNARROW 
OBM_OLD_CLOSE 
OBM_OLD_DNARROW 
OBM_OLD_LFARROW 
OBM_OLD_REDUCE 
OBM_OLD_RESTORE 
OBM_OLD_RGARROW 
OBM_OLD_UPARROW 
OBM_OLD_ ZOOM 
OBM_REDUCE 
OBM_REDUCED 
OBM_RESTORE 

OBM_ RESTORED 
OBM_RGARROW 
OBM_RGARROWD 
OBM_RGARROWI 
OBM_SIZE 
OBM_UPARROW 
OBM_UPARROWD 
OBM_UPARROWI 
OBM_ ZOOM 
OBM_ZOOMD 


Remarks Loads a predefined bitmap used by Windows. 
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Bitmap names that begin with OBM_OLD represent bitmaps used by Windows 
versions prior to 3.0. 


Note that the constant DEMRESOURCE must be defined before including 
WINDOWS.H in order to use any of the OBM_ constants. 


Return Value TRUE if successful; otherwise FALSE. 


See Also CBitmap::LoadBitmap, ::LoadBitmap 


CBitmap::SetBitmapBits 


Syntax DWORD SetBitmapBits( DWORD dwCount, LPSTR /pBits ); 
Parameters dwCount 

Specifies the number of bytes pointed to by lpBits. 

[lpBits 

Points to the BYTE array that contains the bit values to be copied to the 

CBitmap object. 
Remarks Sets the bits of a bitmap to the bit values given by /pBits. 
Return Value The number of bytes used in setting the bitmap bits; 0 if the function fails. 
See Also ::SetBitmapBits 


CBitmap::SetBitmapDimension 


Syntax CSize SetBitmapDimension( int 1 Width, int nHeight ); 
Parameters nWidth 
Specifies the width of the bitmap (in 0.1-millimeter units). 
nHeight 


Specifies the height of the bitmap (in 0.1-millimeter units). 


Remarks 


Return Value 


See Also 
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Assigns a width and height to a bitmap in 0.1-millimeter units. These values are 
not used internally by GDI; the GetBitmapDimension function can be used to re- 
trieve them. 


The previous bitmap dimensions. Height is in the cy member variable of the CSize 
object, and width is in the cx member variable. 


CBitmap::GetBitmapDimension, ::SetBitmapDimension 
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class CBrush : public CGdiObject 


The CBrush class encapsulates a Windows graphical 
design interface (GDI) brush. To use a CBrush object, 
construct a CBrush object and pass it to any CDC 
member function that requires a brush. 


Brushes can be solid, hatched, or patterned. 


See Also CBitmap, CDC 


Public Members 


Construction/Destruction 


CBrush Constructs a CBrush object. 

Initialization 

CreateSolidBrush Initializes a brush with the specified solid color. 

CreateHatchBrush Initializes a brush with the specified hatched pat- 
tern and color. 

CreateBrushIndirect Initializes a brush with the style, color, and pattern 
specified ina LOGBRUSH structure. 

CreatePatternBrush Initializes a brush with a pattern specified by a 
bitmap. 


CreateDIBPatternBrush Initializes a brush with a pattern specified by a 
device-independent bitmap (DIB). 


Operations 


FromHandle Returns a pointer to a CBrush object when given a 
handle to a Windows HBRUSH object. 
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-Member Functions 
CBrush::CBrush 
Syntax CBrush(); 
CBrush( DWORD crColor ) 


throw( CResourceException ); 


CBrush( int n/ndex, DWORD crColor ) 
throw( CResourceException ); 


CBrush( CBitmap* pBitmap ) 
throw( CResourceException ); 


Parameters crColor 
Specifies the foreground color of the brush as an RGB color. If the brush is 
hatched, this parameter specifies the color of the hatching. 


nIndex 
Specifies the hatch style of the brush. It can be any one of the following values: 


Value Meaning 
HS_BDIAGONAL Downward hatch (left to right) at 45 degrees 
HS_CROSS Horizontal and vertical crosshatch 
HS_DIAGCROSS Crosshatch at 45 degrees 
HS_FDIAGONAL Upward hatch (left to right) at 45 degrees 
HS_ HORIZONTAL Horizontal hatch 
HS_ VERTICAL Vertical hatch 

pBitmap 


Points to a CBitmap object that specifies a bitmap with which the brush paints. 
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Remarks 


See Also 


Syntax 


Parameters 


Has four overloaded constructors. The constructor with no arguments constructs 
an uninitialized CBrush object that must be initialized before it can be used. 


If you use the constructor with no arguments, you must initialize the resulting 
CBrush object with CreateSolidBrush, CreateHatchBrush, 
CreateBrushIndirect, CreatePatternBrush, or CreateDIBPatternBrush. If 
you use one of the constructors that takes arguments, then no further initialization 
is necessary. The constructors with arguments can throw an exception if errors are 
encountered, while the constructor with no arguments will always succeed. 


The constructor with a single DWORD parameter constructs a solid brush with 
the specified color. The color specifies an RGB value and can be constructed with 
the RGB macro in WINDOWS.H. 


The constructor with two parameters constructs a hatch brush. The n/ndex parame- 
ter specifies the index of a hatched pattern. The crColor parameter specifies the 
color. 


The constructor with a CBitmap parameter constructs a patterned brush. The 
parameter identifies a bitmap. The bitmap is assumed to have been created by 
using CBitmap::CreateBitmap, CBitmap::CreateBitmapIndirect, 
CBitmap::LoadBitmap, or CBitmap::CreateCompatibleBitmap. The min- 
imum size for a bitmap to be used in a fill pattern is 8 pixels by 8 pixels. 


CBitmap::CreateBitmap, CBitmap::CreateBitmapIndirect, 
CBitmap::LoadBitmap, CBitmap::CreateCompatibleBitmap, 
CBrush::CreateSolidBrush, CBrush::CreateHatchBrush, 
CBrush::CreateBrushIndirect, CBrush::CreatePatternBrush, 
CBrush::CreateDIBPatternBrush, CGdiObject::CreateStockObject 


CBrush::CreateBrushindirect 


BOOL CreateBrushIndirect( LPLOGBRUSH I[pLogBrush ); 


lpLogBrush 
Points to a LOGBRUSH structure that contains information about the brush. 


The LOGBRUSH structure has the following form: 


Remarks 


Return Value 


See Also 


syntax 


Parameters 
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typedef struct tagLOGBRUSH { 
WORD TbStyle; 
COLORREF 1bColor; 
short int \|bHatch; 

} LOGBRUSH; 


Initializes a brush with a style, color, and pattern specified ina LOGBRUSH 
structure. The brush can subsequently be selected as the current brush for any 
device context. 


A brush created using a monochrome (1 plane, 1 bit per pixel) bitmap is drawn 
using the current text and background colors. Pixels represented by a bit set to 0 
will be drawn with the current text color. Pixels represented by a bit set to | will 
be drawn with the current background color. 


TRUE if the function is successful; otherwise FALSE. 


CBrush::CreateDIBPatternBrush, CBrush::CreatePatternBrush, 
CBrush::CreateSolidBrush, CBrush::CreateHatchBrush, 
CGdiObject::CreateStockObject, ::CreateBrushIndirect 


CBrush::CreateD|IBPatternBrush 


BOOL CreateDIBPatternBrush( GLOBALHANDLE hPackedDIB, 
UINT wUsage ); 


hPackedDIB 
Identifies a global-memory object containing a packed device-independent 
bitmap. 


wUsage 
Specifies whether the bmiColors[] fields of the BITMAPINFO data structure 
contain explicit RGB values or indexes into the currently realized logical 
palette. The parameter must be one of the following values: 


Value Meaning 
DIB_PAL_COLORS The color table contains literal RGB values. 


DIB_RGB_COLORS The color table consists of an array of 16-bit 
indexes. 
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Remarks 


Return Value 


See Also 


syntax 


Parameters 


Initializes a brush with the pattern specified by a device-independent bitmap 
(DIB). The brush can subsequently be selected for any device context that sup- 
ports raster operations. 


To obtain a handle to the DIB, you call the Windows GlobalAlloc function to allo- 
cate a block of global memory and then fill the memory with the packed DIB. A 
packed DIB consists of a BITMAPINFO data structure immediately followed by 
the array of bytes that define the pixels of the bitmap. 


The BITMAPINFO structure has the following form: 


typedef struct tagBIIMAPINFO { 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColors[1]; 
} BITMAPINFO; 


Bitmaps used as fill patterns should be 8 pixels by 8 pixels. 


When an application selects a two-color DIB pattern brush into a monochrome 
device context, Windows ignores the colors specified in the DIB and instead dis- 
plays the pattern brush using the current text and background colors of the device 
context. Pixels mapped to the first color (at offset 0 in the DIB color table) of the 
DIB are displayed using the text color. Pixels mapped to the second color (at off- 
set 1 in the color table) are displayed using the background color. 


TRUE if successful; otherwise FALSE. 


CBrush::CreatePatternBrush, CBrush::CreateBrushIndirect, 
CBrush::CreateSolidBrush, CBrush::CreateHatchBrush, 
CGdiObject::CreateStockObject, ::CreateDIBPatternBrush, ::GlobalAlloc 


CBrush::CreateHatchBrush 


BOOL CreateHatchBrush( int nIndex, DWORD crColor ); 


nIndex 
Specifies the hatch style of the brush. It can be one of the following values: 


Remarks 


Return Value | 


See Also 


syntax 


Parameters 


Remarks 
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Value Meaning 
HS_BDIAGONAL Downward hatch (left to right) at 45 degrees 
HS_CROSS Horizontal and vertical crosshatch 
HS_DIAGCROSS Crosshatch at 45 degrees 
HS_FDIAGONAL Upward hatch (left to right) at 45 degrees 
HS_ HORIZONTAL Horizontal hatch 
HS_ VERTICAL Vertical hatch 

crColor 


Specifies the foreground color of the brush as an RGB color (the color of the 
hatches). 


Initializes a brush with the specified hatched pattern and color. The brush can sub- 
sequently be selected as the current brush for any device context. 


TRUE if successful; otherwise FALSE. 


CBrush::CreateBrushIndirect, CBrush::CreateDIBPatternBrush, 
CBrush::CreatePatternBrush, CBrush::CreateSolidBrush, 
CGdiObject::CreateStockObject, ::CreateHatchBrush 


CBrush::CreatePatternBrush 


BOOL CreatePatternBrush( CBitmap* pBitmap ); 


pBitmap 
Identifies a bitmap. 


Initializes a brush with a pattern specified by a bitmap. The brush can sub- 
sequently be selected for any device context that supports raster operations. The 
bitmap identified by pBitmap is typically initialized by using the 
CBitmap::CreateBitmap, CBitmap::CreateBitmapIndirect, 
CBitmap::LoadBitmap, or CBitmap::CreateCompatibleBitmap function. 


Bitmaps used as fill patterns should be 8 pixels by 8 pixels. If the bitmap is larger, 
Windows will only use the bits corresponding to the first 8 rows and columns of 
pixels in the upper-left corner of the bitmap. 
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Return Value 


Cana Alen 
www Finvw 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


A pattern brush can be deleted without affecting the associated bitmap. This — 
means the bitmap can be used to create any number of pattern brushes. 


A brush created using a monochrome bitmap (1 color plane, 1 bit per pixel) is 
drawn using the current text and background colors. Pixels represented by a bit set 
to O are drawn with the current text color. Pixels represented by a bit set to 1 are 
drawn with the current background color. 


TRUE if successful; otherwise FALSE. 


CBrush::CreateBrushindirect, CBrush::CreateDIDPatternbBrusnh, 


CBrush::CreateHatchBrush, CBrush::CreateSolidBrush, 
CGdiObject::CreateStockObject, CBitmap::CreateBitmap, 
CBitmap::CreateBitmapIndirect, CBitmap::CreateCompatibleBitmap, 
CBitmap::LoadBitmap, ::CreatePatternBrush 


CBrush::CreateSolidBrush 


BOOL CreateSolidBrush( DWORD crColor ); 


crColor 
Specifies the color of the brush. The color specifies an RGB value and can be 
constructed with the RGB macro in WINDOWS.H. 


Initializes a brush with a specified solid color. The brush can subsequently be 
selected as the current brush for any device context. 


TRUE if successful; otherwise FALSE. 
CBrush::CreateBrushIndirect, CBrush::CreateDIBPatternBrush, 


CBrush::CreateHatchBrush, CBrush::CreatePatternBrush, 
::CreateSolidBrush 


Syntax 


Parameters 


Remarks 


Return Value 
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CBrush::FromHandle 


static CBrush* FromHandle( HBRUSH Brush ); 


hBrush 
HANDLE to a Windows GDI brush. 


Returns a pointer to a CBrush object when given a handle to a Windows 
HBRUSH object. If a CBrush object is not already attached to the handle, a tem- 
porary CBrush object is created and attached. This temporary CBrush object is 
valid only until the next time the application has idle time in its event loop. At this 
time, all temporary graphic objects are deleted. Another way of saying this is that 
the temporary object is only valid during the processing of one window message. 


A pointer to a CBrush object if successful; NULL if not. 
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class CButton : public CWnd 


The CButton class provides the functionality of Win- 
dows button control. A button control is a small, rec- 
tangular child window that can be clicked on and off. 
Buttons can be used alone or in groups, and can either 
be labeled or appear without text. A button typically 
changes appearance when the user clicks it. 


Typical buttons are the check box, radio button, and push button. A CButton ob- 
ject can become any of these, according to the style specified at its initialization by 
the Create member function. 


You create a button control in two steps. First, call the constructor CButton to con- 
struct the CButton object, then call the Create member function to create the Win- 
dows button control and attach it to the CButton object. 


Construction can be a one-step process in a class derived from CButton. Write a 
constructor for the derived class and call Create from within the constructor. 


If you want to handle the Windows notification messages sent by a CButton ob- 
ject to its parent (usually a class derived from CDialog or CModalDialog), add 
the appropriate message-map entries and message-handler member functions to 
the parent class to handle the messages you want to process. Potential message- 
map entries are: 


ON_ COMMAND 
ON_BN_ CLICKED 
ON_BN_DOUBLECLICKED 


If you create a CButton object within a dialog box (through a dialog resource), the 
CButton object is automatically destroyed when the user closes the dialog box. 


If you create a CButton object within a window, you may also need to destroy it. 
If you create the CButton object on the stack, it is destroyed automatically. If you 
create the CButton object on the heap by using the new function, you must call 
delete on the object to destroy it when the user closes the Windows button control. 


If you allocate any memory in the CButton object, override the CButton destruc- 
tor to dispose of the allocations. 


See Also CWnd, CComboBox, CEdit, CListBox, CScrollBar, CStatic, CModalDialog, 
CDialog 


Public Members 


Construction/Destruction 
CButton 


Initialization 
Create 


Operations 
GetState 
SetState 
GetCheck 
SetCheck 
GetButtonStyle 


SetButtonStyle 
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Constructs a CButton object. 


Creates the Windows button control and attaches it 
to the CButton object. 


Retrieves the state of a button control. 

Sets the highlighting state of a button control. 
Retrieves the check state of a button control. 
Sets the check state of a button control. 


Retrieves information about the button control 
style. 


Changes the style of a button. 
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Member Functions 


Syntax 
Remarks 


See Aiso 


Syntax 


Parameters 


Remarks 


CButton::CButton 


CButton(); 
Constructs a CButton object. 


CButton::Create 


CButton::Create 


BOOL Create( const char FAR* [pCaption, DWORD dwSvple, 
const RECTS& rect, CWnd* pParentWnd, UINT nID ); 


[pCaption 
Specifies the button control’s text. 


dwStyle 
Specifies the button control’s style. 


rect 
Specifies the button control’s size and position. It can be either a CRect object 
or a RECT structure. 


pParentWnd 
Specifies the button control’s parent window, usually a CDialog or 
CModalDialog. It must not be NULL. 


nID 
Specifies the button control’s resource ID. 


You construct a CButton object in two steps. First call the constructor, then call 
Create, which creates the Windows button control and attaches it to the CButton 
object. 


When Create executes, Windows sends the WM_NCCREATE, 
WM_CREATE, WM_NCCALCSIZE, and WM_GETMINMAXINFO 
messages to the button control. 
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These messages are handled by default by the OnNcCreate, OnCreate, 
OnNcCalcSize, and OnGetMinMaxInfo member functions in the CWnd base 
class. To extend the default message handling, derive a class from CButton, add a 
message map to the new class, and override the preceding message-handler mem- 
ber functions. Override OnCreate, for example, to perform needed initialization 
for a new class. 


To handle Windows notification messages that the CButton object sends to its 
parent, add any of the following message-map entries that you want to process to 
the parent-class message map: 


ON_ COMMAND 
ON_BN_ CLICKED 
ON_BN_DOUBLECLICKED 


If the WS_ VISIBLE style is given, Windows sends the button control all the mes- 
sages required to activate and show the button. 


Apply the following window styles to a button control: 


Style Application 

WS_ CHILD Always. 

WS_ VISIBLE Usually. 

WS_DIABLED Rarely. 

WS_ GROUP To group controls. 

WS_TABSTOP To include the button in the tabbing order. 


See CreateEx in the CWnd base class for a full description of these window 
styles. 


Use any combination of the following button styles for dwStyle: 


Value Meaning 


BS_AUTOCHECKBOX Same as a check box, except that an X 
appears in the check box when the user 
selects the box; the X disappears the next 
time the user selects the box. 


BS_AUTORADIOBUTTON Same as a radio button, except that when 
the user selects it, the button automatically 
highlights itself and removes the selection 
from any other radio buttons with the same 
style in the same group. 
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Value 


BS_ AUTO3STATE 


BS_ CHECKBOX 


BS_DEFPUSHBUTTON 


BS_GROUPBOX 


BS_LEFTTEXT 


BS_OWNERDRAW 


BS_ PUSHBUTTON 


Meaning 


Same as a three-state check box, except that 
the box changes its state when the user 
selects it. The state cycles through checked, 
dimmed, and normal. 


Creates a small square that has text 
displayed to its right (unless this style is 
combined with the BS_LEFTTEXT style). 


Creates a button that has a heavy black 
border. The user can select this button by 
pressing the ENTER key. This style is useful 
for enabling the user to quickly select the © 
most likely option (the default option). 


Creates a rectangle in which other buttons 
can be grouped. Any text associated with 
this style is displayed in the rectangle’s 
upper-left corner. 


When combined with a radio-button or 
check-box style, the text appears on the left 
side of the radio button or check box. 


Creates an owner-draw button. The owner 
window receives a 
WM_MEASUREITEM message when 
the button is created and a 
WM_DRAWITEM message when a 
visual aspect of the button has changed. 


Creates a push button that posts a 
WM_COMMAND message to the owner 
window when the user selects the button. 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


Value 


BS_ RADIOBUTTON 


BS_3STATE 
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Meaning 


Creates a small circle that has text 
displayed to its right (unless this style is 
combined with the BS_LEFTTEXT 
style). Radio buttons are usually used in 
groups of related but mutually exclusive 
choices. 


Same as a check box, except that the box 
can be dimmed as well as checked. The 
dimmed state typically 1s used to show that 
a check box has been disabled. 


TRUE if successful; otherwise FALSE. 


CButton::CButton 


CButton::GetButtonStyle 


UINT GetButtonStyleQ const; 


Retrieves the window style of CButton. It only returns the BS_ style values, not 


any of the other window styles. 


See the Create member function for a list of button styles. 


::GetWindowLong, CButton::SetButtonStyle 
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Syntax 
Remarks 


Return Value 


See Also 


syntax 


Return Value 


CButton::GetCheck 


int GetCheck() const; 
Retrieves the check state of a radio button or check box. 
The return value from a button control created with the BS_AUTOCHECKBOX, 


BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_ CHECKBOX, 
BS_ RADIOBUTTON, or BS_3STATE style is one of the following values: 


Value Meaning 

0 Button state is unchecked. 

1 Button state is checked. 

p Button state is indeterminate (only applies if the button has the 


BS_3STATE or BS_AUTO3STATE style). 
If the button has any other style, the return value is 0. 


CButton::GetState, CButton::SetState, CButton::SetCheck, 
BM_GETCHECK 


CButton::GetState 
UINT GetStateQ ut 


Specifies the current state of the button control. You can use the following masks 
against the return value to extract information about the state: 


Mask Meaning 


O0x0003 Specifies the check state (radio buttons and check boxes only). A 
0 indicates the button is unchecked. A 1 indicates the button is 
checked. A radio button is checked when it contains a dot (.). A 
check box is checked when it contains an X. A 2 indicates the 
check state is indeterminate (three-state check boxes only). The 
state of a three-state check box is indeterminate when it contains 
a halftone pattern. 


See Also 


Syntax 


Parameters 


Remarks 


See Also 
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Mask Meaning 


Ox0004 Specifies the highlight state. A nonzero value indicates that the 
button is highlighted. A button is highlighted when the user 
clicks and holds the left mouse button. The highlighting is 
removed when the user releases the mouse button. 


Ox0008 Specifies the focus state. A nonzero value indicates that the 
button has the focus. 


CButton::GetCheck, CButton::SetCheck, CButton::SetState, 
BM_GETSTATE 


CButton::SetButtonStyle 


void SetButtonStyle( UINT nStyle, BOOL bRedraw = TRUE ); 


nStyle 
Specifies the button style. 

bRedraw 
Specifies whether the button is to be redrawn. A value of TRUE redraws the 
button. A value of FALSE does not redraw the button. The button is redrawn 
by default. 


Changes the style of a button. See the Create member function for a list of 
possible button styles. 


CButton::GetButtonStyle, BM_SETSTYLE 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


CButton::SetCheck 


void SetCheck( int nCheck ); 


nCheck 
Specifies the check state. This parameter can be one of the following values: 
Value Meaning 
0 Set the button state to unchecked. 
l Set the button state to checked. 
2 Set the button state to indeterminate. This value can only be 


used if the button has the BS_3STATE or 
BS_ AUTOS3STATE style. 


Sets or resets the check state of a radio button or check box. This member function 
has no effect on a push button. 


CButton::GetCheck, CButton::GetState, CButton::SetState, 
BM_SETCHECK 


CButton::SetState 


void SetState( BOOL bHighlight ); 


bHighlight 
Specifies whether the button is to be highlighted. A value of TRUE highlights 
the button. A value of FALSE removes any highlighting. 


Sets the highlighting state of a button control. 


Highlighting affects the exterior of a button control. It has no effect on the check 
state of a radio button or check box. 


A button control is automatically highlighted when the user clicks and holds the 
left mouse button. The highlighting is removed when the user releases the mouse 
button. 


CButton::GetState, CButton::SetCheck, CButton::GetCheck, 
BM_SETSTATE 
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class CByteArray : public CObject 


See Also 


Public Members 


The CByteArray class supports dynamic arrays of 
bytes. 


The member functions of CByteArray are similar to 
the member functions of class CObArray. Because 
of this similarity, you can use the CObArray reference documentation for mem- 
ber function specifics. Wherever you see a CObject pointer as a function parame- 
ter or return value, substitute a BYTE. 


CObject* CObArray::GetAt( int <nIndex> ) const; 


for example, translates to 


BYTE CByteArray::GetAt( int <nIndex> ) const; 


CByteArray incorporates the IMPLEMENT_SERIAL macro to support serial- 
ization and dumping of its elements. If an array of bytes is stored to an archive, 
either with the overloaded insertion operator or with the Serialize member func- 
tion, each element is, in turn, serialized. 


If you need debug output from individual elements in the array, you must set the 
depth of the CDumpContext object to | or greater. 


#include <afxcoll.h> 


CObArray 


Construction/Destruction 


CByteArray Constructs an empty array for bytes. 

Bounds 

GetSize Gets number of elements in this array. 
GetUpperBound Returns the largest valid index. 

SetSize Sets the number of elements to be contained in this 


array. 


Operations 
FreeExtra 


RemoveAll 


Element Access 
GetAt 
SetAt 


ElementAt 


Growing the Array 
SetAtGrow 


Add 


Insertion/Removal 
InsertAt 


RemoveAt 


Operators 
operator [ | 


Frees all unused memory above the current upper 
bound. | 


Removes all the elements from this array. 


Returns the value at a given index. 


Sets the value for a given index; array not allowed 
to grow. 


Returns a temporary reference to the byte within 
the array. 


Sets the value for a given index; grows the array if 
necessary. 


Adds an element to the end of the array. 


Inserts an element at a specified index. 


Removes an element at a specific index. 


Sets or gets the element at the specified index. 
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class CClientDC : public CDC 


The CClientDC class is derived from CDC and takes 
care of calling the Windows functions GetDC at con- 
struction time and ReleaseDC at destruction time. This 
means that the device context associated with a 
CClientDC object is the client area of a window. 


See Also CDC 


Public Members 


Construction/Destruction 


CClientDC Constructs a CClientDC object connected to the 
CWhnd. 
~CClientDC Destroys a CClientDC object. 


Protected Members 


m_hWnd The HWND of the window for which this 
CClientDC is valid. 
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Member Functions 


Syntax 


Parameters 


Remarks 


Syntax 


Remarks 


CClientDC::CClientDC 


CClientDC( CWnd* pWid ) 
throw( CResourceException ); 


pWnd 
The window whose client area the device context object will access. 


Constructs a CClientDC object that accesses the client area of the CWnd pointed 
to by pWnd. The constructor calls the Windows function GetDC. 


An exception (of type CResourceException) is thrown if the Windows GetDC 
call fails. A device context may not be available if Windows has already allocated 
all of its available device contexts. Your application competes for the five com- 
mon display contexts available at any given time under Windows. 


CClientDC::~CClientDC 


virtual ~CClientDC(); 


Destroys a CClientDC object and calls the Windows ReleaseDC function. 


Data Members 


Remarks 


CClientDC::m_ hWnd 


The HWND of the CWnd pointer used to construct the CClientDC object. 
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class CComboBox : public CWnd 


The CComboBox class provides the functionality of a 
Windows combo box. A combo box consists of an edit 
control plus a list box. The list box may be displayed 
at all times or may be dropped down when the user 
selects a drop-down arrow next to the edit control, 
depending on the style of the combo box. 


Depending on the style of the combo box, the user may or may not be able to edit 
the contents of the edit control. If the list box is visible, typing characters into the 
edit control will cause the first list-box entry that matches the characters typed to 

be highlighted. Conversely, selecting an item in the list box displays the selected 

text in the edit control. 


You create a combo box in two steps. First call the constructor CComboBox to 
construct the CComboBox object, then call the Create member function to create 
the button control and attach it to the CComboBox object. 


Construction can be a one-step process in a class derived from CComboBox. 
Write a constructor for the derived class and call Create from within the 
constructor. 


If you want to handle the Windows notification messages sent by a CComboBox 
object to its parent (usually a class derived from CDialog or CModaIDialog), add 
the appropriate message-map entries and message-handler member functions to 
the parent class to handle the messages you want to process. Potential message- 
map entries are: 


ON_ COMMAND 
ON_CBN_KILLFOCUS 
ON_CBN_SETFOCUS 
ON_CBN_ DROPDOWN 
ON_CBN_DBLCLK 
ON_CBN_ERRSPACE 
ON_CBN_SELCHANGE 
ON_CBN_EDITCHANGE 
ON_CBN_EDITUPDATE 


If you create a CComboBox object within a dialog box (through a dialog re- 
source), the CComboBox is automatically destroyed when the user closes the 
dialog box. 
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See Also 


Public Members 


If you create a CComboBox object within a window, you may also need to de- 
stroy it. If you create the CComboBox object on the stack, it is destroyed automat- 
ically. If you create the CComboBox object on the heap by using the new 
function, you must call delete on the object to destroy it when the user terminates 


the Windows combo box. 


If you allocate any memory in the CComboBox object, override the CComboBox 
destructor to dispose of the allocations. 


CWnd, CButton, CEdit, CListBox, CScrollBar, CStatic, CModalDialog, 


CDialog 


Construction/Destruction 
CComboBox 


Initialization 
Create 


General Operations 
GetCount 


GetCurSel 
SetCurSel 
GetEditSel 
LimitText 
SetEditSel 
GetItemData 


SetItemData 


Constructs a CComboBox object. 


Creates the combo box and attaches it to the 
CComboBox object. 


Retrieves the number of items in the list box of a 
combo box. 


Retrieves the index of the currently selected item, 
if any, in the list box of a combo box. 


Selects a string in the list box of a combo box. 


Gets the starting and ending character positions 
of the current selection in the edit control of a 
combo box. 


Limits the length of the text that the user may enter 
into the edit control of a combo box. 


Select characters in the edit control of a 
combo box. 


Retrieves the application-supplied 32-bit value as- 
sociated with the specified combo-box item. 


Sets the 32-bit value associated with the specified 
item in a combo box. 


GetLBText 
GetLBTextLen 


ShowDropDown 


Clear 
Copy 


Cut 


Paste 


String Operations 
AddString 


DeleteString 
InsertString 
ResetContent 


Dir 
FindString 


SelectString 
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Gets a string from the list box of a combo box. 


Gets the length of a string in the list box of a 
combo box. 


Shows or hides the list box of a combo box that 
has the CBS_ DROPDOWN or 
CBS_DROPDOWNLIST style. 


Deletes (clears) the current selection (if any) in the 
edit control. 


Copies the current selection (if any) onto the 
Clipboard in CF_ TEXT format. 


Deletes (cuts) the current selection (if any) in the 
edit control, and copies the deleted text onto the 
Clipboard in CF_ TEXT format. 


Inserts the data from the Clipboard into the edit 
control at the current cursor position. Data 1s in- 
serted only if the Clipboard contains data in 
CF_TEXT format. 


Adds a string to the end of the list in the list box of 
a combo box, or at the sorted position for list 
boxes with the CBS_SORT style. 


Deletes a string from the list box of a combo box. 
Inserts a string into the list box of a combo box. 


Removes all items from the list box and edit con- 
trol of a combo box. 


Adds a list of filenames to the list box of a 
combo box. 


Finds the first string that contains the specified pre- 
fix in the list box of a combo box. 


Searches for a string in the list box of a combo box 
and, if the string is found, selects the string in the 
list box and copies the string to the edit control. 
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Member Functions 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


syntax 
Remarks 


See Also 


CComboBox::AddString 


int AddString( const char FAR® /pString ); 


lpString 
Points to the null-terminated string that is to be added. 


Adds a string to the list box of a combo box. If the list box was not created with 


the CBS_SORT style, the string is added to the end of the list. Otherwise, the 
string is inserted into the list, and the list is sorted. 


To insert a string into a specific location within the list, use the InsertString 
member function. 


If the return value is greater than or equal to 0, it is the zero-based index to the 
string in the list box. The return value is CB_ ERR if an error occurs; the return 
value is CB_ERRSPACE if insufficient space is available to store the new string. 


CComboBox::InsertString, CComboBox::DeleteString, CB_ADDSTRING 


CComboBox::CComboBox 


CComboBox(); 
Constructs a CComboBox object. 


CComboBox::Create 
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CComboBox::Clear 
Syntax void Clear(); 
Remarks Deletes (clears) the current selection (if any) in the edit control of the combo box. 


To delete the current selection and place the deleted contents onto the Clipboard, 
use the Cut member function. 


See Also CComboBox::Copy, CComboBox::Cut, CComboBox::Paste, WM_CLEAR 


CComboBox::Copy 


Syntax void Copy(); 


Remarks Copies the current selection, if any, in the edit control of the combo box onto the 
Clipboard in CF_TEXT format. 


See Also CComboBox::Clear, CComboBox::Cut, CComboBox::Paste, WM_COPY 


CComboBox::Create 


syntax BOOL Create( DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, 
UINT nID ); 


Parameters dwStyle 
Specifies the style of the combo box. 
rect 


Points to the position and size of the combo box. Can be a RECT structure or a 
CRect object. 


pParentWnd 
Specifies the combo box’s parent window (usually a CDialog or 
CModalDialog). It must not be NULL. 


nD 
Specifies the combo box’s resource ID. 
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Remarks 


CComboBox::Create 


You construct a CComboBox object in two steps. First call the constructor, then 
call Create, which creates the Windows combo box and attaches it to the 
CComboBox object. 


When Create executes, Windows sends the WM_NCCREATE, 
WM_CREATE, WM_NCCALCSIZE, and WM_GETMINMAXINFO 
messages to the combo box. 


These messages are handled by default by the OnNcCreate, OnCreate, 
OnNcCalcSize, and OnGetMinMaxInfo member functions in the CWnd base 
class. To extend the default message handling, derive a class from CComboBox, 
add a message map to the new class, and override the preceding message-handler 
member functions. Override OnCreate, for example, to perform needed initializa- 
tion for a new class. 


To handle Windows notification messages sent from a CComboBox object to its 
parent, add any of the following message-map entries that you want processed to 
the parent-class message map: 


ON_COMMAND 
ON_CBN_KILLFOCUS 
ON_CBN_SETFOCUS 
ON_CBN_DROPDOWN 
ON_CBN_DBLCLK 
ON_CBN_ERRSPACE 
ON_CBN_SELCHANGE 
ON_CBN_EDITCHANGE 
ON_CBN_EDITUPDATE 


Apply the following window styles to a combo-box control: 


Style Application 
WS_ CHILD Always. 
WS_ VISIBLE Usually. 


WS_DIABLED Rarely. 

WS_VSCROLL For list boxes and combo boxes. 
WS_HSCROLL For list boxes and combo boxes. 
WS_GROUP To group controls. 

WS_TABSTOP To include the combo box in the tabbing order. 


See CreateEx in the CWnd base class for a full description of these window 
styles. 
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Use any combination of the following combo-box styles for dwStyle: 


Style Description 


CBS_AUTOHSCROLL Automatically scrolls the text in the 
edit control to the right when the user 
types a character at the end of the line. 
If this style is not set, only text that fits 
within the rectangular boundary is 
allowed. 


CBS_ DROPDOWN Similar to CBS_SIMPLE, except that 
the list box is not displayed unless the 
user selects an icon next to the edit 
control. 


CBS_DROPDOWNLIST Similar to CBS_DROPDOWN, 
except that the edit control is replaced 
by a Static text item that displays the 
current selection in the list box. 


CBS_HASSTRINGS An owner-draw combo-box contains 
items consisting of strings. The combo 
box maintains the memory and pointers 
for the strings so the application can 
use the GetText member function to 
retrieve the text for a particular item. 


CBS_OQEMCONVERT Text entered in the combo-box edit 
control is converted from the ANSI 
character set to the OEM character set 
and then back to ANSI. This ensures 
proper character conversion when the 
application calls the AnsiToOem 
Windows function to convert an ANSI 
String in the combo box to OEM 
characters. This style is most useful for 
combo boxes that contain filenames 
and applies only to combo boxes 
created with the CBS_SIMPLE or 
CBS_ DROPDOWN styles. 


CBS_OWNERDRAWFIXED The owner of the list box is responsible 
for drawing its contents; the items in 
the list box are all the same height. 


CBS_OWNERDRAWVARIABLE _ The owner of the list box is responsible 
for drawing its contents; the items in 
the list box are variable in height. 


146 CComboBox::Cut 


Style | Description 


CBS_SIMPLE | The list box is displayed at all times. 
The current selection in the list box is 
displayed in the edit control. 


CBS_SORT Automatically sorts strings entered into 
the list box. 
Return Value Returns TRUE if successful; otherwise FALSE. 
See Also CComboBox::CComboBox 


CComboBox::Cut 


Syntax void Cut(); 


Remarks Deletes (cuts) the current selection (if any) in the combo-box edit control, and 
copies the deleted text onto the Clipboard in CF_ TEXT format. 


To delete the current selection without placing the deleted text onto the Clipboard, 
call the Clear member function. 


See Also CComboBox::Clear, CComboBox::Copy, CComboBox::Paste, WM_CUT 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 
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CComboBox::DeleteString 


int DeleteString( UINT n/ndex ); 


nindex 


Specifies the index to the string that is to be deleted. 


Deletes a string in the list box of a combo box. 


If the return value is greater than or equal to O, then it 1s a count of the strings re- 
maining in the list. The return value is CB_ERR if n/ndex specifies an index 
greater then the number of items in the list. 


CComboBox::InsertString, CComboBox::AddString, CB_ DELETESTRING 


CComboBox::Dir 


int Dir( UINT attr, const char FAR* /pWildCard ); 


attr 


Can be any combination of the enum values from CFile::GetStatus or any 
combination of the following values: 


Value 

0Ox0000 
Ox0001 
0x0002 
0x0004 
0Ox0010 
0x0020 
0x4000 


Ox8000 


Meaning 

File can be read from or written to. 

File can be read from, but not written to. 

File is hidden and does not appear in a directory listing. 
File is a system file. 

The name specified by /pWildCard specifies a directory. 
File has been archived. 


Include all drives that match the name specified by 
lpWildCard. 


Exclusive flag. If the exclusive flag is set, only files of the 
specified type are listed. Otherwise, files of the specified type 
are listed in addition to “normal” files. 
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Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


lp WildCard 
Points to a file-specification string. The string can contain wildcards (for 
example, *.*). 


Adds a list of filenames and/or drives to the list box of a combo box. 


If the return value is greater than or equal to 0, it is the zero-based index of the last 
filename added to the list. The return value is CB_ ERR if an error occurs; the re- 
turn value is CB_ERRSPACE if insufficient space is available to store the new 
strings. 


CWnd::DigDirList, CB_ DIR, CFile::GetStatus 


CComboBox::FindString 


int FindString( int nStartAfter, const char FAR* [pString ) const; 


nStartAfter 
Contains the zero-based index of the item before the first item to be searched. 
When the search reaches the bottom of the list box, it continues from the top of 
the list box back to the item specified by nStartAfter. If —1, the entire list box is 
searched from the beginning. 

lpString 
Points to the null-terminated string that contains the prefix to search for. The 
search is case-independent, so this string may contain any combination of 
uppercase and lowercase letters. 


Finds, but doesn’t select, the first string that contains the specified prefix in the list 
box of a combo box. 


If the return value is greater than or equal to 0, it is the zero-based index of the 
matching item. It 1s CB_ERR if the search was unsuccessful. 


CComboBox::SelectString, CComboBox::SetCurSel, CB_ FINDSTRING 


Syntax 


Return Value 


See Also 


Syntax 


Return Value — 


See Also 


Syntax 


Remarks 


Return Value 


See Also 
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CComboBox::GetCount 


int GetCount() const; 


The number of items in the list box of a combo box. The returned count is one 
greater then the index value of the last item (the index is zero-based). It is 
CB_ERR if an error occurs. 


CB_GETCOUNT 


CComboBox::GetCurSel 


int GetCurSel() const; 


The zero-based index of the currently selected item in the list box of a combo box, 
or CB_ ERR if no item is selected. 


CComboBox::SetCurSel, CB_GETCURSEL 


CComboBox::GetEditSel 


DWORD GetEditSel() const; 


Gets the starting and ending character positions of the current selection in the edit 
control of a combo box. 


A 32-bit value that contains the starting position in the low-order word and the 
position of the first nonselected character after the end of the selection in the high- 
order word. If this is used on a combo box without an edit control, CB_ERR is 
returned. 


CComboBox::SetEditSel, CB_GETEDITSEL 
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CComboBox::GetitemData 


Syntax DWORD GetItemData( int n/ndex ) const; 


Parameters nIndex 
Contains the zero-based index of an item in the combo box’s list box. 


Remarks Retrieves the application-supplied 32-bit value associated with the specified 
combo-box item. The 32-bit value can be set with the dw/temData parameter of a 
SetItemData member function call. 


Return Value The 32-bit value associated with the item, or CB_ERR if an error occurs. 


See Also CComboBox::SetItemData, CB_GETITEMDATA 


CComboBox::GetLBText 


syntax int GetLBText( int n/ndex, char FAR* [pText ) const; 


void GetLBText( int n/ndex, CString& rString ) const; 


Parameters nIndex 
Contains the zero-based index of the list-box string to be copied.List 
boxes;combo boxes, getting string from, CComboBox::GetLBText 


lpText 
Points to a buffer that is to receive the string. The buffer must have sufficient 
space for the string and a terminating null character. 


rString 
A reference to a CString. 


Remarks Gets a string from the list box of a combo box. The second form of this member 
function fills a CString object with the item’s text. 


Return Value The length (in bytes) of the string, excluding the terminating null character. If 
nIndex does not specify a valid index, the return value is CB_ERR. 


See Also CComboBox::GetLBTextLen, CB_GETLBTEXT 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CComboBox::GetLBTextLen 


int GetLBTextLen( int n/ndex ) const; 


nIndex 
Contains the zero-based index of the list-box string. 


Gets the length of a string in the list box of a combo box. 


The length of the string in bytes, excluding the terminating null character. If 
nIndex does not specify a valid index, the return value is CB_ERR. 


CComboBox::GetLBText, CB_GETLBTEXTLEN 


CComboBox::InsertString 


int InsertString( int n/ndex, const char FAR* [pString ); 


nIndex 
Contains the zero-based index to the position in the list box that will receive the 
string. If this parameter is —1, the string is added to the end of the list. 


lpString 
Points to the null-terminated string that is to be inserted. 


Inserts a string into the list box of a combo box. Unlike the AddString member 
function, the InsertString member function does not cause a list with the 
CBS_SORT style to be sorted. 


The zero-based index of the position at which the string was inserted. The return 
value is CB_ERR if an error occurs. The return value is CB_ERRSPACE if 
insufficient space is available to store the new string. 


CComboBox::AddString, CComboBox::DeleteString, 
CComboBox::ResetContent, CB_INSERTSTRING 
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CComboBox::LimitText 


Syntax BOOL LimitText( int nMaxChars ); 


Parameters nMaxChars 
Specifies the length (in bytes) of the text that the user can enter. If this parame- 
ter is O, the text length is set to 65,535 bytes. 


Remarks Limits the length in bytes of the text that the user may enter into the edit control of 
a combo box. 


If the combo box does not have the style CBS_AUTOHSCROLL, setting the 
text limit to be larger than the size of the edit control will have no effect. 


LimitText only limits the text the user can enter. It has no effect on any text al- 
ready in the edit control when the message is sent, nor does it affect the length of 
the text copied to the edit control when a string in the list box is selected. 


Return Value TRUE if successful. If called for a combo box with the style 
CBS_DROPDOWNLIST or for a combo box without an edit control, the return 
value is CB_ERR. 


See Also CB_LIMITTEXT 
CComboBox::Paste 
Syntax void Paste(); 
Remarks Inserts the data from the Clipboard into the edit control of the combo box at the 


current cursor position. Data is inserted only if the Clipboard contains data in 
CF_TEXT format. 


See Also CComboBox::Clear, CComboBox::Copy, CComboBox::Cut, WM_PASTE 
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CComboBox::ResetContent 


Syntax void ResetContent(); 
Remarks Removes all items from the list box and edit control of a combo box. 
See Also CB_RESETCONTENT 


CComboBox::SelectString 


Syntax int SelectString( int nStartAfter, const char FAR®* /pString ); 


Parameters nStartAfter 
Contains the zero-based index of the item before the first item to be searched. 
When the search reaches the bottom of the list box, it continues from the top of 
the list box back to the item specified by nStartAfter. If —1, the entire list box is 
searched from the beginning. 


lpString 
Points to the null-terminated string that contains the prefix to search for. The 
search is case-independent, so this string may contain any combination of 
uppercase and lowercase letters. 


Remarks Searches for a string in the list box of a combo box, and if the string is found, 
selects the string in the list box and copies it to the edit control. 


A string is selected only if its initial characters (from the starting point) match the 
characters in the prefix string. 


Note that the SelectString and FindString member functions both find a string, 
but the SelectString member function also selects the string. 


Return Value The zero-based index of the selected item if the string was found. If the search 
was unsuccessful, the return value is CB_ ERR and the current selection is not 


changed. 


See Also CComboBox:: FindString, CB_SELECTSTRING 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


CComboBox::SetCurSel 


int SetCurSel( int nSelect ); 


nSelect 
Specifies the zero-based index of the string to select. If —1, any current selec- 
tion in the list box is removed and the edit control is cleared. 


Selects a string in the list box of a combo box. If necessary, the list box scrolls the 
String into view (if the list box is visible). The text in the edit control of the combo 
box is changed to reflect the new selection. Any previous selection in the list box 
is removed. 


The zero-based index of the item selected if the message is successful. The return 
value is CB_ERR if nSelect is greater than the number of items in the list or if 
nSelect is set to —1, which clears the selection. 


CComboBox::GetCurSel, CB_SETCURSEL 


CComboBox::SetEditSel 


BOOL SetEditSel( int nStartChar, int nEndChar ); 


nStartChar 
Specifies the starting position. If the starting position is set to —1, then any 
existing selection is removed. 

nEndChar 
Specifies the ending position. If the ending position is set to —1, then all text 
from the starting position to the last character in the edit control is selected. 


Selects characters in the edit control of a combo box. 


The positions are zero-based. To select the first character of the edit control, you 
specify a starting position of 0. The ending position is for the character just after 
the last character to select. For example, to select the first four characters of the 
edit control, you would use a starting position of 0 and an ending position of 4. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
Return Value 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


CComboBox::ShowDropDown 155 


TRUE if the member function is successful; otherwise FALSE. It is CB_ ERR if 
CComboBox has the CBS_DROPDOWNLIST style or doesn’t have a list box. 


CComboBox::GetEditSel CB_SETEDITSEL 


CComboBox::SetltemData 


int SetItemData( int n/ndex, DWORD dwliItemData ); 


nIndex 
Contains a zero-based index to the item to set. 


dwlItemData 
Contains the new value to associate with the item. 


Sets the 32-bit value associated with the specified item in a combo box. 
CB_ERR if an error occurs. 


CComboBox::GetItemData, CB_SETITEMDATA, CComboBox::AddString, 
CComboBox:: InsertString 


CComboBox::ShowDropDown 


void ShowDropDown( BOOL bShowlIt = TRUE ); 


bShowIt 
Specifies whether the drop-down list box 1s to be shown or hidden. A value of 
TRUE shows the list box. A value of FALSE hides the list box. 


Shows or hides the list box of a combo box that has the CBS_ DROPDOWN or 
CBS_DROPDOWNLIST style. By default, a combo box of this style will show 
the list box. 


This member function has no effect on a combo box created with the 
CBS_SIMPLE style. 


CB_SHOWDROPDOWN 
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class CDC : public CObject 


The CDC class defines a class of device-context ob- 
jects. The CDC object provides member functions 

for working with a device context, such as a display 

or printer, as well as members for working with a dis- 
play context associated with the client area of a window. 


Do all drawing through the member functions of a CDC object. The class provides 
member functions for device-context operations, working with drawing tools, type- 
safe GDI object selection, and working with colors and palettes. It also provides 
member functions for getting and setting drawing attributes, mapping, working 
with the viewport, working with the window extent, converting coordinates, work- 
ing with regions, clipping, drawing lines, drawing simple shapes, ellipses, and 
polygons. Member functions are also provided for drawing text, working with 
fonts, using printer escapes, scrolling, and playing metafiles. 


To use a CDC object, construct it, and then call its member functions, which paral- 
lel Windows functions that use device contexts or display contexts. 


For specific uses, the Microsoft Foundation Class Library provides several classes 
derived from CDC—in particular class CPaintDC, which encapsulates calls to 
BeginPaint and EndPaint. Class CClientDC manages a display context associ- 
ated with a window’s client area. Class CWindowDC manages a display context 
associated with an entire window, including its frame and controls. Class 
CMetaFileDC associates a device context associated with a metafile. 


CDC supports the Attach/Detach idiom for Windows handles described in CWnd. 


See Also CPaintDC, CWindowDC, CClientDC, CMetaFileDC 


Public Members 


Construction/Destruction 
CDC Constructs a CDC object. 
~CDC Destroys a CDC object. 


Initialization 
CreateDC 
CreateIC 


CreateCompatibleDC 


DeleteDC 


Device-Context Functions 
GetDCOrg 


SaveDC 
RestoreDC 


GetDeviceCaps 
Drawing-Tool Functions 


GetBrushOrg 
SetBrushOrg 


EnumObjects 
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Creates a device context for a specific device. 


Creates an information context for a specific de- 
vice. This provides a fast way to get information 
about the device without creating a device context. 


Creates a memory device context that is compat- 
ible with another device context. You can use it to 
prepare images in memory. 


Deletes the Windows DC associated with this 
CDC object. 


Obtains the final translation origin for the device 
context. 


Saves the current state of the device context. 


Restores the device context to a previous state 
saved with SaveDC. 


Retrieves a specified kind of device-specific infor- 
mation about a given display device’s capabilities. 


Retrieves the origin of the current brush. 


Specifies the origin for the next brush selected into 
a device context. 


Enumerates the pens and brushes available in a 
device context. 


Type-Safe Selection Helpers 


SelectObject 
SelectStockObject 


Selects a GDI drawing object, such as a pen. 


Selects one of the predefined stock pens, brushes, 
or fonts provided by Windows. 
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Color and Color Palette Functions 


GetNearestColor 


SelectPalette 
RealizePalette 


UpdateColors 


Retrieves the closest logical color to a specified 
logical color that the given device can represent. 


Selects the logical palette. 


Maps palette entries in the current logical palette to 
the system palette. 


Updates the client area of the device context by 
matching the current colors in the client area to the 
system palette on a pixel-by-pixel basis. 


Drawing-Attribute Functions 


GetBkColor 
SetBkColor 
GetBkMode 
SetBkMode 
GetPolyFillMode 
SetPolyFillMode 
GetROP2 
SetROP2 
GetStretchBltMode 
SetStretchBitMode 
GetTextColor 
SetTextColor 


Mapping Functions 
GetMapMode 
SetMapMode 

Get ViewportOrg 


SetViewportOrg 
Offset ViewportOrg 


GetViewportExt 
Set ViewportExt 


Retrieves the current background color. 
Sets the current background color. 
Retrieves the background mode. 

Sets the background mode. 

Retrieves the current polygon-filling mode. 
Sets the polygon-filling mode. 

Retrieves the current drawing mode. 

Sets the current drawing mode. 

Retrieves the current bitmap-stretching mode. 
Sets the bitmap-stretching mode. 

Retrieves the current text color. 


Sets the text color. 


Retrieves the current mapping mode. 

Sets the current mapping mode. 

Retrieves the x- and y-coordinates of the viewport 
origin. 

Sets the viewport origin. 


Modifies the viewport origin relative to the coordi- 
nates of the current viewport origin. 


Retrieves the x- and y-extents of the viewport. 


Sets the x- and y-extents of the viewport. 


ScaleViewportExt 
GetWindowOrg 


SetWindowOrg 
OffsetWindowOrg 


GetWindowExt 


SetWindowExt 
ScaleWindowExt 


Coordinate Functions 
DPtoLP 


LPtoDP 


Region Functions 
FillRgn 


FrameRgn 


InvertRgen 
PaintRgn 


Clipping Functions 
GetClipBox 


SelectClipRgn 


ExcludeClipRect 


ExcludeUpdateRgn 
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Modifies the viewport extent relative to the current 
values. 


Retrieves the x- and y-coordinates of the origin of 
the associated window. 


Sets the window origin of the device context. 


Modifies the window origin relative to the coordi- 
nates of the current window origin. 


Retrieves the x- and y-extents of the associated 
window. 


Sets the x- and y-extents of the associated window. 


Modifies the window extents relative to the current 
values. 


Converts device points or rectangles into logical 
points or rectangles. 


Converts logical points or rectangles into device 
points or rectangles. 


Fills a specific region with the specified brush. 


Draws a border around a specific region using a 
brush. 


Inverts the colors in a region. 


Fills a region with the selected brush. 


Retrieves the dimensions of the tightest bounding 
rectangle around the current clipping boundary. 


Selects the given region as the current clipping 
region. 


Creates a new clipping region that consists of the 
existing clipping region minus the specified rec- 
tangle. 

Prevents drawing within invalid areas of a window 


by excluding an updated region in the window 
from a clipping region. 
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IntersectClipRect 


OffsetClipRgn 
PtVisible 


RectVisible 


Line-Output Functions 
GetCurrentPosition 


MoveTlo 
LineTo 


Arc 
Polyline 


Simple Drawing Functions 


FillRect 
FrameRect 
InvertRect 


DrawlIcon 


Creates a new clipping region by forming the inter- 
section of the current region and a rectangle. 


Moves the clipping region of the given device. 


Specifies whether the given point is within the clip- 
ping region. 


Determines whether any part of the given rectangle 
lies within the clipping region. 


Retrieves the current position of the pen (in logical 
coordinates). 


Moves the current position. 


Draws a line from the current position up to, but 
not including, a point. 


Draws an elliptical arc. 


Draws a set of line segments connecting the 
specified points. 


Fills a given rectangle by using a specific brush. 
Draws a border around a rectangle. 
Inverts the contents of a rectangle. 


Draws an icon. 


Ellipse and Polygon Functions 


Chord 
DrawFocusRect 
Ellipse 

Pie 

Polygon 


PolyPolygon 


Draws a chord (a closed figure bounded by the in- 
tersection of an ellipse and a line segment). 


Draws a rectangle in the style used to indicate 
focus. 


Draws an ellipse. 
Draws a pie-shaped wedge. 


Draws a polygon consisting of two or more points 
(vertices) connected by lines. 


Creates two or more polygons that are filled using 
the current polygon-filling mode. The polygons 
may be disjoint or they may overlap. 


Rectangle 


RoundRect 


Bitmap Functions 
PatBit 

BitBit 

StretchBlt 


GetPixel 
SetPixel 


FloodFill 
ExtFloodFill 


Text Functions 
TextOut 


ExtTextOut 
TabbedTextOut 


DrawText 
GetTextExtent 


GetTabbedTextExtent 


GrayString 
GetTextAlign 
SetTextAlign 
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Draws a rectangle using the current pen and filled 
using the current brush. 


Draws a rectangle with rounded corners using the 
current pen and filled using the current brush. 


Creates a bit pattern. 
Copies a bitmap from a specified device context. 


Moves a bitmap from a source rectangle and de- 
vice into a destination rectangle, stretching or com- 
pressing the bitmap if necessary to fit the 
dimensions of the destination rectangle. 


Retrieves the RGB color value of the pixel at the 
specified point. 


Sets the pixel at the specified point to the closest 
approximation of the specified color. 


Fills an area with the current brush. 


Fills an area with the current brush. Provides more 
flexibility than the FloodFill member function. 


Writes a character string at a specified location, 
using the currently selected font. 


Writes a character string within a rectangular re- 
gion, using the currently selected font. 


Writes a character string at a specified location, ex- 
panding tabs to the values specified in an array of 
tab-stop positions. 


Draws formatted text in the specified rectangle. 


Computes the width and height of a line of text, 
using the current font to determine the dimensions. 


Computes the width and height of a character 
String. 


Draws dimmed (gray) text at the given location. 
Retrieves the text-alignment flags. 


Sets the text-alignment flags. 
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GetTextFace 


GetTextMetrics 
SetText Justification 


GetTextCharacterExtra 


SetTextCharacterExtra 


Font Functions 
GetCharWidth 
SetMapperFlags 


GetAspectRatioFilter 


Printer Escape Functions 
Escape 


StartDoc 
StartPage 


EndPage 
SetAbortProc 


AbortDoc 


EndDoc 


Copies the typeface name of the current font into a 
buffer as a null-terminated string. 


Retrieves the metrics for the current font. 
Adds space to the break characters in a string. 


Retrieves the current setting for the amount of 1n- 
tercharacter spacing. 


Sets the amount of intercharacter spacing. 


Retrieves the widths of individual characters in a 
consecutive group of characters from the current 
font. 


Alters the algorithm that the font mapper uses 
when it maps logical fonts to physical fonts. 


Retrieves the setting for the current aspect-ratio 
filter. 


Allows applications to access facilities of a particu- 
lar device that are not directly available through 
GDI. Escape calls made by an application are trans- 
lated and sent to the device driver. 


Informs the device driver that a new print job 1s 
starting. 


Informs the device driver that a new page is 
starting. 


Informs the device driver that a page is ending. 


Sets a programmer-supplied callback function that 
Windows calls if a print job must be aborted. 


Terminates the current print job, erasing every- 
thing the application has written to the device since 
the last EndDoc escape. 


Ends a print job started by a StartDoc escape. 
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Scrolling Functions 


ScrolIDC Scrolls a rectangle of bits horizontally and 
vertically. 


Metafile Functions 


PlayMetaFile Plays the contents of the specified metafile on the 
given device. The metafile can be played any num- 
ber of times. 
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Member Functions 


CDC::AbortDoc 


Syntax int AbortDoc(); 


Remarks Terminates the current print job, erasing everything the application has written to 
the device since the last call to EndDoc. 


This member function is provided as a convenient way to send the ABORTDOC 
escape. It allows the application to access facilities of a particular device that are 
not directly available through GDI. The escape call is translated and sent to the 
device driver. 


AbortDoc should be used to terminate: 


= Printing operations that do not specify an abort function using SetAbortProc. 


= Printing operations that have not yet reached their first NEWFRAME or 
NEXTBAND escape call. 


If an application encounters a printing error or a canceled print operation, it must 
not attempt to terminate the operation by using either the EndDoc or AbortDoc 
member functions of class CDC. GDI automatically terminates the operation 
before returning the error value. 


If the application displays a dialog box to allow the user to cancel the print opera- 
tion, it must call AbortDoc before destroying the dialog box. 


Return Value A positive value if successful, or a negative value if an error has occurred. The fol- 
lowing list shows common error values: 


See Also 


Syntax 


Parameters 
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Value Meaning 

SP_ ERROR General error. 

SP_OUTOFDISK Not enough disk space 1s currently available for 
spooling, and no more space will become 
available. 

SP_OUTOFMEMORY Not enough memory is available for spooling. 

SP_USERABORT User terminated the job through the Print 
Manager. 

::AbortDoc 


CDC::Arc 


BOOL Arc( int x/, int y/, int x2, int y2, int x3, int y3, int x4, int y4 ); 


BOOL Arc( LPRECT [pRect, POINT ptStart, POINT ptEnd ); 


xl 
Specifies the x-coordinate of the upper-left corner of the bounding rectangle (in 
logical units). 

yl 
Specifies the y-coordinate of the upper-left corner of the bounding rectangle Gin 
logical units). 

9 
Specifies the x-coordinate of the lower-right corner of the bounding rectangle 
(in logical units). 

y2 
Specifies the y-coordinate of the lower-right corner of the bounding rectangle 
(in logical units). 
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Remarks 


Return Value 


See Also 


x3 
Specifies the x-coordinate of the point that defines the arc’s starting point (in 
logical units). This point does not have to lie exactly on the arc. 


y3 
Specifies the y-coordinate of the point that defines the arc’s starting point (in 
logical units). This point does not have to lie exactly on the arc. 


x4 
Specifies the x-coordinate of the point that defines the arc’s endpoint (in logical 
units). This point does not have to lie exactly on the arc. 


y4 
Specifies the y-coordinate of the point that defines the arc’s endpoint (in logical 
units). This point does not have to lie exactly on the arc. 


lpRect 
Specifies the bounding rectangle (in logical units). You can pass either a 
LPRECT or a CRect object for this parameter. 


ptStart 
Specifies the x- and y-coordinates of the point that defines the arc’s starting 
point (in logical units). This point does not have to lie exactly on the arc. You 
can pass either a POINT structure or a CPoint object for this parameter. 


ptEnd 
Specifies the x- and y-coordinates of the point that defines the arc’s ending 
point (in logical units). This point does not have to lie exactly on the arc. You 
can pass either a POINT structure or a CPoint object for this parameter. 


Draws an elliptical arc. The arc drawn by using the function is a segment of the el- 
lipse defined by the specified bounding rectangle. 


The actual starting point of the arc is the point at which a ray drawn from the cen- 
ter of the bounding rectangle through the specified starting point intersects the el- 
lipse. The actual ending point of the arc is the point at which a ray drawn from the 
center of the bounding rectangle through the specified ending point intersects the 
ellipse. The arc is drawn in a counterclockwise direction. Since an arc is not a 
closed figure, it is not filled. 


TRUE if the arc is drawn; otherwise FALSE. 


CDC::Chord, ::Are 


Syntax 


Parameters 
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CDC::BitBit 


BOOL BitBIt( int x, int y, int nWidth, int nHeight, CDC* pSrcDC, int xSrc, 
int ySrc, DWORD dwkRop ); 


x 
Specifies the logical x-coordinate of the upper-left corner of the destination rec- 
tangle. 


y 
Specifies the logical y-coordinate of the upper-left corner of the destination rec- 


tangle. 


nWidth 
Specifies the width (in logical units) of the destination rectangle and source bit- 
map. 


nHeight 
Specifies the height (in logical units) of the destination rectangle and source bit- 
map. 


pSrcDC 
Pointer to a CDC object that identifies the device context from which the bit- 
map will be copied. It must be NULL if dwRop specifies a raster operation that 
does not include a source. 


xSrc 
Specifies the logical x-coordinate of the upper-left corner of the source bitmap. 


ySre | 
Specifies the logical y-coordinate of the upper-left corner of the source bitmap. 


dwRop 
Specifies the raster operation to be performed. Raster-operation codes define 
how the graphics device interface (GDI) combines colors in output operations 
that involve a current brush, a possible source bitmap, and a destination bitmap. 
The following lists raster-operation codes for dwRop: 


Code Description 

BLACKNESS Turns all output black. 

DSTINVERT Inverts the destination bitmap. 

MERGECOPY Combines the pattern and the source bitmap using the 
Boolean AND operator. 


MERGEPAINT Combines the inverted source bitmap with the 
destination bitmap using the Boolean OR operator. 
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Remarks 


CDC::BitBlt 


Code Description 

NOTSRCCOPY Copies the inverted source bitmap to the destination. 

NOTSRCERASE Inverts the result of combining the destination and 
source bitmaps using the Boolean OR operator. 

PATCOPY Copies the pattern to the destination bitmap. 

PATINVERT Combines the destination bitmap with the pattern 
using the Boolean XOR operator. 

PATPAINT Combines the inverted source bitmap with the pattern 
using the Boolean OR operator. Combines the result 
of this operation with the destination bitmap using the 
Boolean OR operator. 

SRCAND Combines pixels of the destination and source 
bitmaps using the Boolean AND operator. 

SRCCOPY Copies the source bitmap to the destination bitmap. 

SRCERASE Inverts the desination bitmap and combines the result 
with the source bitmap using the Boolean AND 
operator. 

SRCINVERT Combines pixels of the destination and source 
bitmaps using the Boolean XOR operator. 

SRCPAINT Combines pixels of the destination and source 
bitmaps using the Boolean OR operator. 

WHITENESS Turns all output white. 


For a complete list of raster-operation codes, see the Windows Software 
Development Kit documentation. 


Copies a bitmap from the source device context to this current device context. 


The application can align the windows or client areas on byte boundaries to ensure 
that the BitBIt operations occur on byte-aligned rectangles. (Set the 
CS_BYTEALIGNWINDOW or CS_ BYTEALIGNCLIENT flags when you 
register the window classes.) 


Return Value 


See Also 


Syntax 
Remarks 


See Also 
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BitBlt operations on byte-aligned rectangles are considerably faster than BitBlt 
operations on rectangles that are not byte aligned. If you want to specify class 
styles such as byte-alignment or your own device context, you will have to register 
a window class rather than relying on the Foundation classes to do it for you. Use 
the Foundation global function AfxRegisterWndClass. 


GDI transforms nWidth and nHeight, once by using the destination display con- 
text, and once by using the source display context. If the resulting extents do not 
match, GDI uses the Windows StretchBlt function to compress or stretch the 
source bitmap as necessary. 


If destination, source, and pattern bitmaps do not have the same color format, the 
BitBlt function converts the source and pattern bitmaps to match the destination. 
The foreground and background colors of the destination are used in the conver- 

sion. 


Note that not all device contexts support BitBIt. To check whether a given device 
context does support BitBIt, use GetDeviceCaps. 


TRUE if the bitmap is drawn; otherwise FALSE. 


CDC::GetDeviceCaps, CDC::PatBIt, CDC::SetTextColor, CDC::StretchBit, 
::StretchDIBits, ::BitBlt 


CDC::CDC 


CDCOQ; 
Constructs a CDC object. 


CDC::CreateDC, CDC::CreateIC 
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Syntax 


Remarks 


See Also 


Syntax 


Parameters 


CDC::~CDC 


virtual ~CDCQ; 


Destroys a CDC object. If a Windows HDC is attached to the CDC object, the de- 
structor detaches the HDC and deletes it. 


CDC::DeleteDC, ::DeleteDC 


CDC::Chord 


BOOL Chord( int x/, int y/, int x2, int y2, int x3, int y3, int x4, int y4 ); 
BOOL Chord( LPRECT /pRect, POINT ptStart, POINT ptEnd ); 


xl 
Specifies the x-coordinate of the upper-left corner of the chord’s bounding rec- 
tangle (in logical units). 
yl 
Specifies the y-coordinate of the upper-left corner of the chord’s bounding rec- 
tangle (in logical units). 
x2 
Specifies the x-coordinate of the lower-right corner of the chord’s bounding rec- 
tangle (in logical units). 
y2 
Specifies the y-coordinate of the lower-right corner of the chord’s bounding rec- 
tangle (in logical units). 
x3 
Specifies the x-coordinate of the point that defines the chord’s starting point (in 
logical units). 
y3 , 
Specifies the y-coordinate of the point that defines the chord’s starting point (in 
logical units). 


x4 
Specifies the x-coordinate of the point that defines the chord’s endpoint (in logi- 
cal units). 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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y4 
Specifies the y-coordinate of the point that defines the chord’s endpoint (in logi- 
cal units). 


lpRect 
Specifies the bounding rectangle (in logical units). You can pass either a 
LPRECT or a CRect object for this parameter. 


ptStart 
Specifies the x- and y-coordinates of the point that defines the chord’s starting 
point (in logical units). This point does not have to lie exactly on the chord. 
You can pass either a POINT structure or a CPoint object for this parameter. 


ptEnd 
Specifies the x- and y-coordinates of the point that defines the chord’s ending 
point (in logical units). This point does not have to lie exactly on the chord. 
You can pass either a POINT structure or a CPoint object for this parameter. 


Draws a chord (a closed figure bounded by the intersection of an ellipse and a line 
segment). The (x/, y/) and (x2, y2) parameters specify the upper-left and lower- 
right corners, respectively, of a rectangle bounding the ellipse that is part of the 
chord. The (x3, y3) and (x4, y4) parameters specify the endpoints of a line that in- 
tersects the ellipse. The chord is drawn by using the selected pen and filled by 
using the selected brush. 


TRUE if the chord is drawn: otherwise FALSE. 


CDC::Arc, ::Chord 


CDC::CreateCompatibleDC 


BOOL CreateCompatibleDC( CDC* pDC ); 


pDC 
A pointer to a device context. If pDC is NULL, the function creates a memory 
device context that is compatible with the system display. 


Creates a memory device context that is compatible with the device specified by 
pDC. A memory device context is a block of memory that represents a display sur- 
face. It can be used to prepare images in memory before copying them to the ac- 
tual device surface of the compatible device. 


When a memory device context is created, GDI automatically selects a 1-by-1 
monochrome stock bitmap for it. 
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Return Value 


See Also 


Syntax 


Parameters 


This function can only be used to create compatible device contexts for devices 
that support raster operations. For more information, see the RC_ BITBLT raster 
capability in the member function GetDeviceCaps. GDI output functions can be 
used with a memory device context only if a bitmap has been created and selected 
into that context. 


TRUE if successful; otherwise FALSE. 


CDC::CDC, CDC::GetDeviceCaps, ::CreateCompatibleDC 


CDC::CreateDC 


BOOL CreateDC( const char FAR* [pDriverName, 
const char FAR* /pDeviceName, const char FAR®* /pOutput, 
LPSTR [pInitData ); 


lpDriverName 
Points to a null-terminated string that specifies the MS-DOS filename (without 
extension) of the device driver (for example, EPSON). You can also pass a 
CString object for this parameter. 


lpDeviceName 
Points to a null-terminated string that specifies the name of the specific device 
to be supported (for example, EPSON FX-80). The [pDeviceName parameter is 
used if the module supports more than one device. You can also pass a CString 
object for this parameter. 


[pOutput 
Points to a null-terminated string that specifies the MS-DOS file or device 
name for the physical output medium (file or output port). You can also pass a 
CString object for this parameter. 


[pInitData 
Points toa DEVMODE structure containing device-specific initialization data 
for the device driver. The Windows ExtDeviceMode function retrieves this 
structure filled in for a given device. The /pInitData parameter must be NULL 
if the device driver is to use the default initialization (if any) specified by the 
user through the Control Panel. 


The DEVMODE structure has the following form: 


Remarks 


Return Value 


See Also 
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Parameters 
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dAinclude <drvinit.h> 


typedef struct _devicemode { 


char dmDeviceName[32]; 
WORD dmSpecVersion; 
WORD dmDriverVersion; 


WORD dmSize; 
WORD dmDriverExtra; 
DWORD dmmembers; 
Short dmOrientation; 
short dmPaperSize; 
short dmPaperLength; 
short dmPaperwWidth; 
short dmScale; 
short dmCopies; 
short dmDefaultSource; 
Short dmPrintQuality; 
Short dmColor; 
short dmDuplex; 

} DEVMODE; 


Creates a device context for the specified device. The [pDriverName, 
IpDeviceName, and lpOutput parameters specify the device driver, device name, 
and physical output medium (file or port), respectively. 


The DRVINIT.H header file is required if the DEVMODE structure is used. 
TRUE if successful; otherwise FALSE. 


::ExtDeviceMode, ::CreateDC 


CDC::CreatelC 


BOOL CreateIC( const char FAR* [pDriverName, 
const char FAR* /pDeviceName, const char FAR* [pOutput, 
LPSTR [pInitData ); 


lpDriverName 
Points to a null-terminated string that specifies the MS-DOS filename (without 
extension) of the device driver (for example, EPSON). You can pass a CString 
object for this parameter. 


IpDeviceName 
Points to a null-terminated string that specifies the name of the specific device 
to be supported (for example, EPSON FX-80). The JpDeviceName parameter 1s 
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Remarks 


Return Value 


See Also 


Syntax 


Remarks 


used if the module supports more than one device. You can pass a CString ob- 
ject for this parameter. 


[pOutput 
Points to a null-terminated string that specifies the MS-DOS file or device 
name for the physical output medium (file or port). You can pass a CString ob- 
ject for this parameter. 


lpInitData 
Points to device-specific initialization data for the device driver. The [p/nitData 
parameter must be NULL if the device driver is to use the default initialization 
(if any) specified by the user through the Control Panel. See CreateDC for the 
data format for device-specific initialization. 


Creates an information context for the specified device. The information context 
provides a fast way to get information about the device without creating a device 
context. 


MS-DOS device names follow MS-DOS conventions; an ending colon (:) is rec- 
ommended, but optional. Windows strips the terminating colon so that a device 
name ending with a colon is mapped to the same port as the same name without a 
colon. The driver and port names must not contain leading or trailing spaces. GDI 
output functions cannot be used with information contexts. 


TRUE if successful; otherwise FALSE. 


CDC::CreateDC, ::CreateIC 


CDC::DeleteDC 


BOOL DeleteDCQ; 


In general, do not call this function; the destructor will do it for you. The 
DeleteDC member function deletes the Windows function DC attached to the cur- 
rent CDC object. If this CDC object is the last active device context for a given 
device, the device is notified and all storage and system resources used by the de- 
vice are released. 


An application must not delete a device context whose handle was obtained by cal- 
ling CWnd::GetDC. Instead, it must call CWnd::ReleaseDC to free the device 
context. The CClientDC class is provided to wrap this functionality. 


The DeleteDC function is generally used to delete device contexts created with 
CreateDC, CreateIC, or CreateCompatibleDC. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 
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Specifies whether the device context has been deleted. TRUE if the device context 
is successfully deleted (regardless of whether the deleted device context is the last 
context for the device). FALSE if an error occurs. 


CDC::CDC, CDC::~CDC, ::DeleteDC 


CDC::DPtoLP 


void DPtoLP( LPPOINT /pPoints, int nCount = 1 ) const; 
void DPtoLP( LPRECT /pRect ) const; 


lpPoints 
Points to an array of POINT structures or CPoint objects. 


nCount 
Specifies the number of points in the array. 


[pRect | 
Points to a RECT structure or CRect object. This parameter is used for the 
simple case of converting one rectangle from device points to logical points. 


Converts device points into logical points. The function maps the coordinates of 
each point from the device coordinate system into GDI’s logical coordinate sys- 
tem. The conversion depends on the current mapping mode and the settings of the 
origins and extents for the device’s window and viewport. 


CDC::LPtoDP, ::DPtoLP 


CDC::DrawFocusRect 


void DrawFocusRect( LPRECT [pRect ); 
[pRect 
Points to a RECT structure or a CRect object that specifies the coordinates of 


the rectangle to be drawn. 


Draws a rectangle in the style used to indicate focus. 
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See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Since this is an XOR function, calling this function a second time with the same 
rectangle removes the rectangle from the display. The rectangle drawn by this 
function cannot be scrolled. To scroll an area containing a rectangle drawn by this 
function, first call DrawFocusRect to remove the rectangle from the display, then 
scroll the area, and then call DrawFocusRect again to draw the rectangle in the 
new position. 


::DrawFocusRect 


CDC::Drawlcon 


BOOL Drawlcon( int x, int y, HICON /hlcon ); 
BOOL DrawlIcon( POINT point, HICON hlcon ); 


- | 
Specifies the logical x-coordinate of the upper-left corner of the icon. 


Specifies the logical y-coordinate of the upper-left corner of the icon. 


hiIcon 
Identifies the handle of the icon to be drawn. 


point 
Specifies the logical x- and y-coordinates of the upper-left corner of the icon. 
You can pass a POINT structure or a CPoint object for this parameter. 


Draws an icon on the device represented by the current CDC object. The function 
places the icon’s upper-left corner at the location specified by x and y. The loca- 
tion is subject to the current mapping mode of the device context. 


The icon resource must have been previously loaded by using the functions 
CWinApp::LoadIcon, CWinApp::LoadStandardIcon, or 
CWinApp::LoadOEMIcon. The MM_TEXT mapping mode must be selected 
prior to using this function. 


TRUE if the function is successful; otherwise FALSE. 


CWinApp::Loadicon, CWinApp::LoadStandardIcon, 
CWinApp::LoadOEMIcon, ::DrawlIcon 


CDC::DrawText 


CDC::DrawText 177 


Syntax int DrawText( const char FAR®* [pString, int nCount, LPRECT /pRect, 


UINT nFormat ); 


Parameters [IpString 


Points to the string to be drawn. If nCount is —1, the string must be null- 


terminated. 


nCount 


Specifies the number of bytes in the string. If nCount is —1, then [pString is as- 
sumed to be a long pointer to a null-terminated string and DrawText computes 


the character count automatically. 


[pRect 


Points to a RECT structure or CRect object that contains the rectangle (in logi- 
cal coordinates) in which the text is to be formatted. 


nFormat 


Specifies the method of formatting the text. It can be any combination of the fol- 
lowing values (combine using the bitwise-OR operator): 


Value 
DT_BOTTOM 


DT_CALCRECT 


DT_CENTER 
DT_EXPANDTABS 


Meaning 


Specifies bottom-justified text. This value 
must be combined with 
DT_SINGLELINE. 


Determines the width and height of the 
rectangle. If there are multiple lines of 
text, DrawText will use the width of the 
rectangle pointed to by /pRect and extend 
the base of the rectangle to bound the last 
line of text. If there 1s only one line of 
text, DrawText will modify the right side 
of the rectangle so that it bounds the last 
character in the line. In either case, 
DrawText returns the height of the 
formatted text but does not draw the text. 


Centers text horizontally. 


Expands tab characters. The default 
number of characters per tab is eight. 
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Value 
DT_EXTERNALLEADING 


DT_LEFT 
DT_NOCLIP 


DT_NOPREFIX 


DT_RIGHT 
DT_SINGLELINE 


DT_TABSTOP 


DT_TOP 
DT_VCENTER 


DT_WORDBREAK 


Meaning 


Includes the font’s external leading in the 
line height. Normally, external leading is 
not included in the height of a line of text. 


Aligns text flush-left. 


Draws without clipping. DrawText is 
somewhat faster when DT_NOCLIP is 
used. 


Turns off processing of prefix characters. 
Normally, DrawText interprets the 
ampersand (&) mnemonic-prefix 
character as a directive to underscore the 
character that follows, and the two- 
ampersand (&&) mnemonic-prefix 
characters as a directive to print a single 
ampersand. By specifiying 
DT_NOPREFIX this processing is 
turned off. 


Aligns text flush-right. 


Specifies single line only. Carriage returns 
and linefeeds do not break the line. 


Sets tab stops. The high-order byte of 
nFormat is the number of characters for 
each tab. The default number of 
characters per tab is eight. 


Specifies top-justified text (single line 
only). 


Specifies vertically centered text (single 
line only). 


Specifies word-breaking. Lines are 
automatically broken between words if a 
word would extend past the edge of the 
rectangle specified by /pRect. A carriage 
return—linefeed sequence will also break 
the line. 
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Note that the values DT_CALCRECT, DT_EXTERNALLEADING, 
DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values cannot be 
used with the DT_TABSTOP value. 


Draws formatted text in the rectangle specified by /pRect. It formats text by ex- 
panding tabs into appropriate spaces, aligning text to the left, right, or center of the 
given rectangle, and breaking text into lines that fit within the given rectangle. The 
type of formatting is specified by nFormat. 


This member function uses the device context’s selected font, text color, and back- 
ground color to draw the text. Unless the DT_NOCLIP format is used, 
DrawText clips the text so that the text does not appear outside the given rec- 
tangle. All formatting 1s assumed to have multiple lines unless the 
DT_SINGLELINE format is given. 


If the selected font is too large for the specified rectangle, the DrawText member 
function does not attempt to substitute a smaller font. 


The height of the text. 


::DrawText 


CDC::Ellipse 


BOOL Ellipse( int x/, int y/, int x2, int y2 ); 
BOOL Ellipse( LPRECT /pRect ); 


xl 
Specifies the logical x-coordinate of the upper-left corner of the ellipse’s bound- 
ing rectangle. 

yl 
Specifies the logical y-coordinate of the upper-left corner of the ellipse’s bound- 
ing rectangle. 


x2 
Specifies the logical x-coordinate of the lower-right corner of the ellipse’s 
bounding rectangle. 
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y2 


Specifies the logical y-coordinate of the lower-right corner of the ellipse’s 
bounding rectangle. 


lpRect 
Specifies the ellipse’s bounding rectangle. You can also pass a CRect object 
for this parameter. 


Draws an ellipse. The center of the ellipse is the center of the bounding rectangle 
specified by x/, y/, x2, and y2, or lpRect. The ellipse is drawn with the current pen 
and its interior is filled with the current brush. 


If either the width or the height of the bounding rectangle is 0, no ellipse is drawn. 
TRUE if the ellipse is drawn; otherwise FALSE. 


CDC::Arc, CDC::Chord, ::Ellipse 


CDC::EndDoe 


int EndDoc(Q); 


Ends a print job started by a call to the StartDoc member function. 


The member function is provided as a convenient way to send the ENDDOC 
escape. It allows the application to access facilities of a particular device that are 
not directly available through GDI. The escape call is translated and sent to the 
device driver. 


If an application encounters a printing error or a canceled print operation, it must 
not attempt to terminate the operation by using either EndDoc or AbortDoc. GDI 
automatically terminates the operation before returning the error value. 


Positive if the function is successful. Or a negative value if there is an error. The 
following list shows common error values: 


See Also 


Syntax 


Remarks 


Return Value 


Value 


SP_ERROR 
SP_OUTOFDISK 


SP_OUTOFMEMORY 
SP_USERABORT 


::EndDoc 


CDC::EndPage 


int EndPage(Q); 
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Meaning 


General error. 


Not enough disk space is currently available for 
spooling, and no more space will become 
available. 


Not enough memory is available for spooling. 


User terminated the job through the Print 
Manager. 


Informs the device that the application has finished writing to a page. This mem- 
ber function is typically used to direct the device driver to advance to a new page. 


The member function is provided as a convenient way to send the NEWFRAME 
escape. It allows the application to access facilities of a particular device that are 
not directly available through GDI. The escape call is translated and sent to the 


device driver. 


Positive if successful; otherwise, it is an error value, which can be one of the fol- 


lowing: 
Value 


SP_ERROR 
SP_APPABORT 


SP_USERABORT 


Meaning 


General error. 


Job was terminated because the application’s abort 
function returned zero. 


User terminated the job through Print Manager. 
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Value Meaning 


SP_OUTOFDISK Not enough disk space is currently available for 
spooling, and no more space will become available. 


SP_OUTOFMEMORY Not enough memory is available for spooling. 


CDC::StartPage, CDC::StartDoc, ::EndPage 


CDC::EnumObjects 


int EnumObjects( int nObjectType, 
int (FAR PASCAL EXPORT* /pfn )( LPSTR, LPSTR ), LPSTR /pData ); 


nObjectType 
Specifies the object type. It can have the values OBJ. BRUSH or OBJ_ PEN. 


lpfn 
Is the procedure-instance address of the application-supplied callback function. 
See the “Remarks” section below. 


[pData 


Points to the application-supplied data. The data is passed to the callback func- 
tion along with the object information. 


Enumerates the pens and brushes available in a device context. For each object of 
a given type, the callback function that you pass is called with the information for 
that object. The system calls the callback function until there are no more objects 
or the callback function returns 0. 


Note that new features of Microsoft C/C++ let you use an ordinary function as the 
function passed to EnumObjects. The address passed to EnumObjects is a FAR 
pointer to a function exported with __ export and with the Pascal calling conven- 
tion. In protect-mode applications, you do not have to create this function with the 
Windows MakeProclInstance function or free the function after use with 
FreeProcInstance. 
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You also do not have to export the function name in an EXPORTS statement in 
your application’s module-definition file. You can instead use the __ export func- 
tion modifier, as in 


int FAR PASCAL __ export AFunction( LPSTR, LPSTR ); 


to cause the compiler to emit the proper export record for export by name without 
aliasing. This works for most needs. For some special cases, such as exporting a 
function by ordinal or aliasing the export, you still need to use an EXPORTS 
statement in a module-definition file. 


For compiling Foundation programs, you’ll normally use the /GA and /GEs com- 
piler options. The /Gw compiler option is not used with the Foundation classes. (If 
you do use MakeProclInstance, you will need to explicitly cast the returned func- 
tion pointer from FARPROC to the type needed in this API.) Callback registra- 
tion interfaces are now type-safe (you must pass in a function pointer that points to 
the right kind of function for the specific callback). 


Also note that all callback functions must trap Foundation exceptions before re- 
turning to Windows, since exceptions cannot be thrown across callback boundar- 
ies. For more information about exceptions, see Chapter 12 in the Class Libraries 
User’s Guide. 


Callback Function 


The callback function passed to EnumObjects must use the Pascal calling conven- 
tion and must be declared FAR. 


int FAR PASCAL __ export ObjectFunc( LPSTR lpLogObject, 
LPSTR* [pData ); 


The ObjectFunc name is a placeholder for the application-supplied function name. 
The actual name must be exported as described in the “Remarks” section above. 


Parameter Description 

[pLogObject Points to a LOGPEN or LOGBRUSH data structure that 
contains information about the logical attributes of the 
object. 

[pData Points to the application-supplied data passed to the 


EnumObjects function. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


The callback function returns an int. The value of this return is user-defined. If the 
callback function returns 0, EnumObjects stops enumeration early. 


Specifies the last value returned by the callback function. Its meaning is user- 
defined. 


::FreeProcInstance, ::MakeProcInstance, ::EnumObjects 


CDC::Escape 
int Escape( int nEscape, int nCount, LPSTR [pInData, LPSTR [pOutData ); 


nEscape 
Specifies the escape function to be performed. For a complete list of escape 
functions, see the chapter on printer escapes in the Windows Software Develop- 
ment Kit documentation. 


nCount 
Specifies the number of bytes of data pointed to by [p/nData. 


lpInData 
Points to the input data structure required for this escape. 


lpOutData 
Points to the structure that is to receive output from this escape. The [pOutData 
parameter is NULL if no data is returned. 


Allows applications to access facilities of a particular device that are not directly 
available through GDI. Escape calls made by an application are translated and sent 
to the device driver. 


The nEscape parameter specifies the escape function to be performed. For 
possible values, see the chapter on printer escapes in the Windows Software 
Development Kit documentation. 


The Microsoft Foundation Class Library provides member functions for some of 
the most common escape functions. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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Positive if the function is successful, except for the QUERYESCSUPPORT 
escape, which only checks for implementation. Or 0 if the escape is not imple- 
mented. Or a negative value if there is an error. The following list shows common 
error values: 


Value Meaning 

SP_ERROR General error. 

SP_OUTOFDISK Not enough disk space is currently available for 
spooling, and no more space will become 
available. 

SP_OUTOFMEMORY Not enough memory is available for spooling. 

SP_USERABORT User terminated the job through the Print 
Manager. 


CDC::StartDoc, CDC::StartPage, CDC::EndPage, CDC::SetAbortProc, 
CDC::AbortDoc, CDC::EndDoc, ::Escape 


CDC::ExcludeClipRect 


int ExcludeClipRect( int x/, int y/, int x2, int y2 ); 
int ExcludeClipRect( LPRECT [pRect ); 


xl 
Specifies the logical x-coordinate of the upper-left corner of the rectangle. 


yl 
Specifies the logical y-coordinate of the upper-left corner of the rectangle. 


XZ 

Specifies the logical x-coordinate of the lower-right corner of the rectangle. 
y2 

Specifies the logical y-coordinate of the lower-right corner of the rectangle. 


lpRect 
Specifies the rectangle. 


Creates a new clipping region that consists of the existing clipping region minus 
the specified rectangle. 
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Return Value 


See Also 


Syntax 


Parameters 
Remarks 


Return Value 


See Also 


Specifies the new clipping region’s type. It can be any one of the following values: 


Value Meaning 

COMPLEXREGION The region has overlapping borders. 
ERROR No region was created. 
NULLREGION The region is empty. 
SIMPLEREGION The region has no overlapping borders. 
::ExcludeClipRect 


CDC::ExcludeUpdateRgn 


int ExcludeUpdateRgn( CWnd* pWahd ); 


pWnd 
Points to the window object whose window is being updated. 


Prevents drawing within invalid areas of a window by excluding an updated re- 
gion in the window from the clipping region associated with the CDC object. 


The type of excluded region. It can be any one of the following values: 


Value Meaning 

COMPLEXREGION The region has overlapping borders. 
ERROR No region was created. 
NULLREGION The region is empty. 
SIMPLEREGION The region has no overlapping borders. 


::ExcludeUpdateRgen 


Syntax 


Parameters 


Remarks 


CDC::ExtFloodFill 187 


CDC::ExtFloodFill 


BOOL ExtFloodFill( int x, int y, DWORD crColor, UINT nFillType ); 


x 
Specifies the logical x-coordinate of the point where filling begins. 


Specifies the logical y-coordinate of the point where filling begins. 


crColor 
Specifies the color of the boundary or of the area to be filled. The interpretation 
of crColor depends on the value of nFillType. 


nFillType 
Specifies the type of flood fill to be performed. It must be one of the following 
values: 


Value Meaning 


FLOODFILLBORDER The fill area is bounded by the color 
specified by crColor. This style is identical 
to the filling performed by FloodFill. 


FLOODFILLSURFACE The fill area is defined by the color specified 
by crColor. Filling continues outward in all 
directions as long as the color is 
encountered. This style is useful for filling 
areas with multicolored boundaries. 


Fills an area of the display surface with the current brush. However, this member 
function provides more flexibility than FloodFill. You can specify a fill type in 
nFillType. 


If nFillType is set to FLOODFILLBORDER, the area is assumed to be 
completely bounded by the color specified by crColor. The function begins at the 
point specified by x and y and fills in all directions to the color boundary. 


If nFillType is set to FLOODFILLSURFACE, the function begins at the point 
specified by x and y and continues in all directions, filling all adjacent areas con- 
taining the color specified by crColor. 


Only memory-device contexts and devices that support raster-display technology 
support ExtFloodFill. For more information see the GetDeviceCaps member 
function. 
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Return Value 


See Also 


Syntax 


Parameters 


TRUE if the function is successful. FALSE if the filling could not be completed, 
if the given point has the boundary color specified by crColor (if 
FLOODFILLBORDER was requested), if the given point does not have the 
color specified by crColor if FLOODFILLSURFACE was requested), or if the 
point is outside the clipping region. 


CDC::FloodFill, CDC::GetDeviceCaps, ::ExtFloodFill 


CDC::ExtTextOut 


BOOL ExtTextOut( int x, int y, UINT nOptions, LPRECT /pRect, 
const char FAR®* /pString, UINT nCount, LPINT [pDxWidths ); 


X 
Specifies the logical x-coordinate of the character cell for the first character in 
the specified string. 


Specifies the logical y-coordinate of the character cell for the first character in 
the specified string. 


nOptions 
Specifies the rectangle type. This parameter can be one, both, or neither of the 
following values: 


Value Meaning 
ETO_CLIPPED Specifies that text is clipped to the rectangle. 


ETO_OPAQUE Specifies that the current background color fills the 
rectangle. 


[pRect 
Points to a RECT structure that determines the dimensions of the rectangle. 
This parameter can be NULL. You can also pass a CRect object for this para- 
meter. 


lpString 
Points to the specified character string. You can also pass a CString object for 
this parameter. 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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nCount 
Specifies the number of characters in the string. 


[lpDxWidths 
Points to an array of values that indicate the distance between origins of adja- 
cent character cells. For instance, [pDxWidths{[i] logical units will separate the 
origins of character cell i and character cell i + 1. This parameter can be NULL. 


Writes a character string within a rectangular region, using the currently selected 
font. The rectangular region can be opaque (filled with the current background 
color) and it can be a clipping region. 


If nOptions is 0 and lpRect is NULL, the function writes text to the device context 
without using a rectangular region. By default, the current position is not used or 
updated by the function. If an application needs to update the current position 
when it calls ExtTextOut, the application can call the CDC member function 
SetTextAlign with nFlags set to TA. UPDATECP. When this flag is set, Win- 
dows ignores x and y on subsequent calls to ExtTextOut, using the current posi- 
tion instead. 


TRUE if the function is successful; otherwise FALSE. 


CDC::SetTextAlign, CDC::TabbedTextOut, CDC::TextOut, ::ExtTextOut 


CDC::FillRect 


void FillRect( LPRECT /pRect, CBrush* pBrush ); 


lpRect 
Points to a RECT or CRect that contains the logical coordinates of the rec- 
tangle to be filled. You can also pass a CRect object for this parameter. 


pBrush 
Identifies the brush used to fill the rectangle. 


Fills a given rectangle by using the specified brush. The function fills the complete 
rectangle, including the left and top borders, but does not fill the right and bottom 
borders. 
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See Also 


Syntax 


Parameters 


Remarks 
Return Value 


See Also 


syntax 


Parameters 


When filling the specified rectangle, FillRect does not include the rectangle’s 
right and bottom sides. GDI fills a rectangle up to, but does not include, the right 
column and bottom row, regardless of the current mapping mode. FillRect com- 
pares the values of the top, bottom, left, and right members of the specified rec- 
tangle. If bottom is less than or equal to top, or if right is less than or equal to 
left, the rectangle is not drawn. 


CBrush, ::FillRect 


CDC::FillRgn 
BOOL FillRgn( CRgn* pRen, CBrush* pBrush ); 
pRgn 


Identifies the region to be filled. The coordinates for the given region are 
specified in device units. 


pBrush 
Identifies the brush to be used to fill the region. 


Fills the region specified by pRgn with the brush specified by pBrush. 
TRUE if the function is successful or FALSE 1f an error occurs. 


CRgn, CDC::PaintRgn, CBrush, ::FillRgn 


CDC::FloodFill 


BOOL FloodFill( int x, int y, DWORD crColor ); 


x 
Specifies the logical x-coordinate of the point where filling begins. 


Specifies the logical y-coordinate of the point where filling begins. 


crColor 
Specifies the color of the boundary. 


Remarks 


Return Value 


See Also 


syntax 


Parameters 


Remarks 


See Also 
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Fills an area of the display surface with the current brush. The area is assumed to 
be bounded as specified by crColor. The FloodFill function begins at the point 
specified by x and y and continues in all directions to the color boundary. 


Only memory-device contexts and devices that support raster-display technology 
support the FloodFill member function. For information about RC_BITBLT 
capability, see the GetDeviceCaps member function. 


The ExtFloodFill function provides similar capability but greater flexibility. 


TRUE if the function is successful. FALSE if the filling could not be completed, 
the given point has the boundary color specified by crColor, or the point is outside 
the clipping region. 


CDC::ExtFloodFill, CDC::GetDeviceCaps, ::FloodFill 


CDC::FrameRect 


void FrameRect( LPRECT /pRect, CBrush* pBrush ); 


lpRect 
Points to a RECT or CRect that contains the logical coordinates of the upper- 
left and lower-right corners of the rectangle. You can also pass a CRect object 
for this parameter. 


pBrush 
Identifies the brush to be used for framing the rectangle. 


Draws a border around the rectangle specified by /[pRect. The function uses the 
given brush to draw the border. The width and height of the border is always one 
logical unit. 


If the rectangle’s bottom coordinate is less than or equal to top, or if right is less 
than or equal to left, the rectangle is not drawn. 


CBrush, ::FrameRect 
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CDC::FrameRgn 


syntax BOOL FrameRgn( CRgn* pRen, CBrush* pBrush, int nWidth, int nHeight ); 


Parameters pRen 
Points to the CRgn object that identifies the region to be enclosed in a border. 
The coordinates for the given region are specified in device units. 


pBrush 
Points to the CBrush object that identifies the brush to be used to draw the 
border. 


nWidth 
Specifies the width in vertical brush strokes (in logical units). 


nHeight 
Specifies the height in horizontal brush strokes (in logical units). 


Remarks Draws a border around the region specified by pRgn, using the brush specified by 
pBrush. The nWidth parameter specifies the width of the border in vertical brush 
strokes; nHeight specifies the height in horizontal brush strokes. 


Return Value TRUE if the function is successful; otherwise FALSE. 


See Also ::FrameRgn, CBrush, CRgen 


CDC::GetAspectRatioFilter 


Syntax CSize GetAspectRatioFilterQ const; 


Remarks Retrieves the setting for the current aspect-ratio filter. The aspect ratio is the ratio 
formed by a device’s pixel width and height. Information about a device’s aspect 
ratio is used in the creation, selection, and display of fonts. Windows provides a 
special filter, the aspect-ratio filter, to select fonts designed for a particular aspect 
ratio from all of the available fonts. The filter uses the aspect ratio specified by 
SetMapperFlags. 


Return Value A CSize object representing the aspect ratio used by the current aspect-ratio filter. 


See Also CDC::SetMapperFlags, ::GetAspectRatioFilter, CSize 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 
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CDC::GetBkColor 


DWORD GetBkColor() const; 


Returns the current background color. If the background mode is OPAQUE, the 
system uses the background color to fill the gaps in styled lines, the gaps between 
hatched lines in brushes, and the background in character cells. The system also 
uses the background color when converting bitmaps between color and mono- 
chrome device contexts. 

An RGB color value. 


CDC::GetBkMode, CDC::SetBkColor, CDC::SetBkMode, ::GetBkColor 


CDC::GetBkMode 


int GetBkMode() const; 


Returns the background mode. The background mode defines whether the system 
removes existing background colors on the drawing surface before drawing text, 
hatched brushes, or any pen style that is not a solid line. 


Specifies the current background mode. It can bb OPAQUE or TRANSPARENT. 


CDC::GetBkColor, CDC::SetBkColor, CDC::SetBkMode, ::GetBkMode 


CDC::GetBrushOrg 


CPoint GetBrushOrg() const; 


Retrieves the origin of the brush currently selected for the device context. 


The initial brush origin is at (0,0) of the client area. The return value specifies this 
point in device units relative to the origin of the desktop window. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Specifies the current origin of the brush (in device units) as a CPoint object. 


CDC::SetBrushOrg, CGdiObject::UnrealizeObject, ::GetBrushOrg 


CDC::GetCharWidth 


BOOL GetCharWidth( UINT nFirstChar, UINT nLastChar, 
LPINT /pBuffer ) const; 


nFirstChar 
Specifies the first character in a consecutive group of characters in the current 
font. 


nLastChar 
Specifies the last character in a consecutive group of characters in the current 
font. 


lpBuffer 
Points to a buffer that will receive the width values for a consecutive group of 
characters in the current font. 


Retrieves the widths of individual characters in a consecutive group of characters 
from the current font. For example, if nFirstChar identifies the letter "a’ and 
nLastChar identifies the letter 'z', the function retrieves the widths of all lower- 
case characters. 


The function stores the values in the buffer pointed to by /pBuffer. This buffer 
must be large enough to hold all of the widths. For example, there must be at least 
26 entries in the example given in the previous paragraph. 


If a character in the consecutive group of characters does not exist in a particular 
font, it will be assigned the width value of the default character. 


TRUE if the function is successful; otherwise FALSE. 


::;<GetCharWidth 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 
Remarks 
Return Value 


See Also 


CDC::GetCurrentPosition 195 


CDC::GetClipBox 


int GetClipBox( LPRECT /pRect ) const; 


[pRect 
Points to the RECT or CRect that is to receive the rectangle dimensions. 


Retrieves the dimensions of the tightest bounding rectangle around the current clip- 
ping boundary. The dimensions are copied to the buffer pointed to by /pRect. 


The clipping region’s type. It can be any one of the following values: 
Value Meaning 


COMPLEXREGION Clipping region has overlapping borders. 


ERROR Device context is not valid. 
NULLREGION Clipping region is empty. 
SIMPLEREGION Clipping region has no overlapping borders. 
::GetClipBox 


CDC::GetCurrentPosition 


CPoint GetCurrentPosition() const; 
Retrieves the current position (in logical coordinates). 
The current position as a CPoint object. 


CDC::MoveTo, CPoint, ::GetCurrentPosition 
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Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


CDC::GetDCOrg 


CPoint GetDCOrg() const; 


Obtains the final translation origin for the device context. The final translation 
origin specifies the offset used by Windows to translate device coordinates into 
client coordinates for points in an application’s window. The final translation 
origin is relative to the physical origin of the screen display. 


The final translation origin (in device coordinates) as a CPoint object. 


CPoint, ::GetDCOrg 


CDC::GetDeviceCaps 


int GetDeviceCaps( int n/ndex ) const; 


nIndex 

Specifies the item to return. It can be any one of the following values: 

DRIVERVERSION 
Version number; for example, 0x100 for 1.0. 

TECHNOLOGY 
Device technology. It can be any one of the following values: 
Value Meaning 
DT_PLOTTER Vector plotter 
DT_RASDISPLAY Raster display 
DT_RASPRINTER Raster printer 
DT_RASCAMERA Raster camera 
DT_CHARSTREAM Character stream 
DT_METAFILE Metafile 
DT_DISPFILE Display file 

HORZSIZE 


Width of the physical display (in millimeters). 
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VERTSIZE 
Height of the physical display (in millimeters). 


HORZRES 

Width of the display (in pixels). 
VERTRES 

Height of the display (in raster lines). 


LOGPIXELSX 
Number of pixels per logical inch along the display width. 


LOGPIXELSY 
Number of pixels per logical inch along the display height. 


BITSPIXEL 
Number of adjacent color bits for each pixel. 


PLANES 
Number of color planes. 


NUMBRUSHES 
Number of device-specific brushes. 


NUMPENS 
Number of device-specific pens. 


NUMFONTS 
Number of device-specific fonts. 


NUMCOLORS 
Number of entries in the device’s color table. 


ASPECTX 
Relative width of a device pixel as used for line drawing. 


ASPECTY 
Relative height of a device pixel as used for line drawing. 


ASPECTXY 
Diagonal width of the device pixel as used for line drawing. 


PDEVICESIZE 
Size of the PDEVICE internal data structure. 


CLIPCAPS 
Flag that indicates the clipping capabilities of the device. Itis 1 if the device 
can clip to a rectangle, 0 if it cannot. 


SIZEPALETTE 
Number of entries in the system palette. This index is valid only if the device 
driver sets the RC_PALETTE bit in the RASTERCAPS index. It is availa- 
ble only if the driver version is 3.0 or higher. 
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NUMRESERVED 
Number of reserved entries in the system palette. This index is valid only if 
the device driver sets the RC_PALETTE bit in the RASTERCAPS index 
and is available only if the driver version is 3.0 or higher. 


COLORRES 
Actual color resolution of the device in bits per pixel. This index is valid 
only if the device driver sets the RC_PALETTE bit in the RASTERCAPS 
index and is available only if the driver version is 3.0 or higher. 


RASTERCAPS 
Value that indicates the raster capabilities of the device, as shown in the fol- 


lowing list: 
Capability 
RC_BANDING 
RC_BITBLT 
RC_BITMAP64 


RC_DI_BITMAP 
RC_DIBTODEV 


RC_FLOODFILL 
RC_GDI20_ OUTPUT 


RC_PALETTE 
RC_SCALING 
RC_STRETCHBLT 


RC_STRETCHDIB 


Meaning 


Requires banding support 
Capable of transferring bitmaps 


Capable of supporting bitmaps larger than 
64K 


Capable of supporting SetDIBits and 
GetDIBits 


Capable of supporting the 
SetDIBitsToDevice function 


Capable of performing flood fills 


Capable of supporting Windows version 2.0 
features 


Palette-based device 
Capable of scaling 


Capable of performing the StretchBlt 
function 


Capable of performing the StretchDIBits 
function 


CURVECAPS 
A bitmask that indicates the curve capabilities of the device. The bits have 
the following meanings: 
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Bit Meaning 
0 Device can do circles 
1 Device can do pie wedges 
2 Device can do chord arcs 
3 Device can do ellipses 
4 Device can do wide borders 
5 Device can do styled borders 
6 Device can do borders that are wide and styled 
i Device can do interiors 
The high byte is 0. 
LINECAPS 


A bitmask that indicates the line capabilities of the device. The bits have the 
following meanings: 


Bit Meaning 


Reserved 

Device can do polyline 
Reserved 

Reserved 

Device can do wide lines 
Device can do styled lines 


Device can do lines that are wide and styled 


SYN nN FW NY KF © 


Device can do interiors 


The high byte is 0. 
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POLYGONALCAPS 
A bitmask that indicates the polygonal capabilities of the device. The bits 
have the following meanings: 


Bit Meaning 


0 Device can do alternate fill polygon 
1 Device can do rectangle 
2 Device can do winding number fill polygon 
3 Device can do scanline 
4 Device can do wide borders 
5 Device can do styled borders 
6 Device can do borders that are wide and styled 
qd Device can do interiors 
The high byte is 0. 
TEXTCAPS 
A bitmask that indicates the text capabilities of the device. The bits have the 
following meanings: 


Bit Meaning 


Device can do character output precision 
Device can do stroke output precision 
Device can do stroke clip precision 

Device can do 90-degree character rotation 
Device can do any character rotation 

Device can do scaling independent of x and y 
Device can do doubled character for scaling 
Device can do integer multiples for scaling 


Device can do any multiples for exact scaling 


CW AHNTNWD ANA FP WN KF OS 


Device can do double-weight characters 


Remarks 


Return Value 


See Also 
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Remarks 


Return Value 


See Also 


CDC::GetMapMode 


Bit Meaning 


10 Device can do italicizing 


11 Device can do underlining 

12 Device can do strikeouts 

13 Device can do raster fonts 

14 Device can do vector fonts 
15 Reserved; must be returned 0 


Retrieves device-specific information about a given display device. The nlndex 
parameter specifies the type of information desired. 


The value of the desired item. 


::GetDeviceCaps 


CDC::GetMapMode 


int GetMapMode() const; 


Retrieves the current mapping mode. 


See SetMapMode for a description of the mapping modes. 
The mapping mode. 


CDC::SetMapMode, ::GetMapMode 
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CDC::GetNearestColor 


DWORD GetNearestColor( DWORD crColor ) const; 


crColor 
Specifies the color to be matched. 


Returns the closest logical color to a specified logical color that the given device 
can represent. 


An RGB color value that names the solid color closest to the crColor value that 
the device can represent. 


::GetNearestColor 


CDC::GetPixel 


DWORD GetPixel( int x, int y ) const; 
DWORD GetPixel( POINT point ) const; 


x 
Specifies the logical x-coordinate of the point to be examined. 


Specifies the logical y-coordinate of the point to be examined. 


point 
Specifies the logical x- and y-coordinates of the point to be examined. 


Retrieves the RGB color value of the pixel at the point specified by x and y. The 
point must be in the clipping region. If the point is not in the clipping region, the 
function has no effect and returns —1. 


Not all devices support the GetPixel function. For more information, see the 
RC_BITBLT raster capability under the GetDeviceCaps member function. 


The GetPixel member function has two forms. The first takes two coordinate 
values; the second takes either a POINT structure or a CPoint object. 


Return Value 


See Also 
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See Also 
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See Also 
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For either version of the function, an RGB color value for the color of the given 
point. It is —1 if the coordinates do not specify a point in the clipping region. 


CDC::GetDeviceCaps, CDC::SetPixel, ::GetPixel 


CDC::GetPolyFillMode 


int GetPolyFillMode() const; 


Retrieves the current polygon-filling mode. 


See the SetPolyFillMode member function later in this reference for a description 
of the polygon filling modes. 


CDC::SetPolyFillMode, ::GetPolyFillMode 


CDC::GetROP2 


int GetROP2() const; 


Retrieves the current drawing mode. The drawing mode specifies how the colors 
of the pen and the interior of filled objects are combined with the color already on 
the display surface. 


The drawing mode. For a list of the drawing mode values, see SetROP2. 


CDC::GetDeviceCaps, CDC::SetROP2, ::GetROP2 
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Remarks 
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CDC::GetStretchBltMode 


int GetStretchBltMode() const; 


Retrieves the current bitmap-stretching mode. The bitmap-stretching mode defines 
how information is removed from bitmaps that are stretched or compressed by 
using StretchBit. 


The BLACKONWHITE and WHITEONBLACK modes are typically used to 
preserve foreground pixels in monochrome bitmaps. 


The COLORONCOLOR mode is typically used to preserve color in color 
bitmaps. 


The current bitmap-stretching mode. It can bob WHITEONBLACK, 
BLACKONWHITE, or COLORONCOLOR. 


CDC::StretchBlit, CDC::SetStretchBltMode, ::GetStretchBltMode 


CDC::GetfabbedTextExtent 


CSize GetTabbed TextExtent( const char FAR* /pString, int nCount, 
int nTabPositions, LPINT l[pnTabStopPositions ) const; 


lpString 
Points to a character string. You can also pass a CString object for this 
parameter. 


nCount 
Specifies the number of characters in the string. 


nTabPositions 
Specifies the number of tab-stop positions in the array pointed to by 
lpnTabStopPositions. 


[pnTabStop Positions 
Points to an array of integers containing the tab-stop positions in pixels. The tab 
stops must be sorted in increasing order; back tabs are not allowed. 


Computes the width and height of a character string. If the string contains one or 
more tab characters, the width of the string is based upon the tab stops specified 
by [pnTabStopPositions. The function uses the currently selected font to compute 
the dimensions of the string. 


Return Value 


See Also 
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Since some devices do not place characters in regular cell arrays (that is, they kern 
the characters), the sum of the extents of the characters in a string may not be 
equal to the extent of the string. 


If nTabPositions is 0 and IpnTabStopPositions is NULL, tabs are expanded to 
eight average character widths. 


If nTabPositions is 1, the tab stops will be separated by the distance specified by 
the first value in the array to which /pnTabStopPositions points. 


If IpnTabStopPositions points to more than a single value, a tab stop is set for each 
value in the array, up to the number specified by nTabPositions. 


The dimensions of the string (in logical units). 


CDC::GetTextExtent, CDC::TabbedTextOut, ::GetTabbedTextExtent 


CDC::GetTextAlign 


UINT GetTextAlignQ const; 


Retrieves the status of the text-alignment flags for the device context. 


The text-alignment flags determine how TextOut and ExtTextOut align a string 
of text in relation to the string’s starting point. The text-alignment flags are not 
necessarily single-bit flags and may be equal to 0. To test whether a flag is set, an 
application should follow these steps: 


1. Apply the bitwise-OR operator to the flag and its related flags. The following 
list shows the groups of related flags: 


» TA_LEFT, TA_CENTER, and TA_ RIGHT 

" TA_BASELINE, TA_ BOTTOM, and TA_ TOP 

*" TA_NOUPDATECP and TA_UPDATECP 
2. Apply the bitwise AND operator to the result and the return value. 
3. Test for the equality of this result and the flag. 


The status of the text-alignment flags. The return value is one or more of the fol- 
lowing values: 
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Value Meaning 

TA_ BASELINE Specifies alignment of the x-axis and the 
baseline of the chosen font within the bounding 
rectangle. 

TA_ BOTTOM Specifies alignment of the x-axis and the 


bottom of the bounding rectangle. 


TA_CENTER Specifies alignment of the y-axis and the center 
of the bounding rectangle. 


TA_LEFT Specifies alignment of the y-axis and the left 
side of the bounding rectangle. 


TA_NOUPDATECP Specifies that the current position is not 


updated. 
TA_ RIGHT Specifies alignment of the y-axis and the right 
side of the bounding rectangle. 
TA_TOP Specifies alignment of the x-axis and the top of 
the bounding rectangle. 
TA_UPDATECP Specifies that the current position is updated. 
See Also CDC::ExtTextOut, CDC::SetTextAlign, CDC::TextOut, ::GetTextAlign 


CDC::GetTextCharacterExtra 


Syntax int GetTextCharacterExtra() const; 


Remarks Retrieves the current setting for the amount of intercharacter spacing. GDI adds 
this spacing to each character, including break characters, when it writes a line of 
text to the device context. 


Return Value The amount of the intercharacter spacing. 


See Also CDC::SetTextCharacterExtra, ::GetTextCharacterExtra 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CDC::GetTextColor 


DWORD GetTextColor() const; 


Retrieves the current text color. The text color is the foreground color of charac- 
ters drawn by using the GDI text-output functions TextOut, ExtTextOut, and 
TabbedTextOut. 


The current text color as an RGB color value. 


CDC::GetBkColor, CDC::GetBkMode, CDC::SetBkMode, CDC::SetText- 
Color, ::GetTextColor 


CDC::GetTextExtent 


CSize GetTextExtent( const char FAR* [pString, int nCount ) const; 


lpString 
Points to a string of characters. You can also pass a CString object for this para- 
meter. 


nCount 
Specifies the number of characters in the string. 


Computes the width and height of a line of text, using the current font to determine 
the dimensions. 


Since some devices do not place characters in regular cell arrays (that is, they 


carry out kerning), the sum of the extents of the characters in a string may not be 
equal to the extent of the string. 


The dimensions of the string (in logical units). 


CDC::GetTabbedTextExtent, ::GetTextExtentEx, CDC::SetTextJustification 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Return Value 


See Also 


CDC::GetTextFace 


int GetTextFace( int nCount, const char FAR* [pFacename ) const; 


nCount 
Specifies the size of the buffer (in bytes). If the typeface name is longer than 
the number of bytes specified by this parameter, the name is truncated. 


lpFacename 
Points to the buffer for the typeface name. 


Copies the typeface name of the current font into a buffer. The typeface name is 
copied as a null-terminated string. 


The number of bytes copied to the buffer. It is O if an error occurs. 


CDC::GetTextMetrics, CDC::SetTextAlign, CDC::TextOut, ::GetTextFace 


CDC::GetTextMetrics 


BOOL GetTextMetrics( LPTEXTMETRIC [pMetrics ) const; 


lpMetrics 
Points to the TEX TMETRIC structure that receives the metrics. @HO = Re- 
marks 


Retrieves the metrics for the current font. 
TRUE if the function is successful; otherwise FALSE. 


CDC::GetTextAlign, CDC::GetTextExtent, CDC::GetTextFace, 
CDC::SetText Justification, ::GetTextMetrics 


Syntax 
Remarks 
Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 
Remarks 
Return Value 


See Also 


CDC::GetWindowExt 209 


CDC::GetViewportExt 


CSize Get ViewportExt() const; 
Retrieves the x- and y-extents of the device context’s viewport. 
The x- and y-extents (in device units) as a CSize object. 


CSize, ::GetViewportExt 


CDC::GetViewportOrg 


CPoint Get ViewportOrg() const; 


Retrieves the x- and y-coordinates of the origin of the viewport associated with the 
device context. 


The origin of the viewport (in device coordinates) as a CPoint object. 


CPoint, ::GetViewportOrg 


CDC::GetWindowExt 


CSize GetWindowExt() const; 
Retrieves the x- and y-extents of the window associated with the device context. 
The x- and y-extents (in logical units) as a CSize object. 


CSize, ::GetWindowExt 
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syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


CDC::GetWindowOrg 


CPoint GetWindowOrg() const; 


Retrieves the x- and y-coordinates of the origin of the window associated with the 
device context. 


The origin of the window (in logical coordinates) as a CPoint object. 


CPoint, ::GetWindowOrg 


CDC::GrayString 


BOOL GrayString( CBrush* pBrush, 
BOOL (FAR PASCAL EXPORT*® [pfnOutput )( HDC, DWORD, int ), 
DWORD [pData, int nCount, int x, int y, int nWidth, int nHeight ); 


pBrush 
Identifies the brush to be used for dimming (graying). 


lpfnOutput 
Specifies the procedure-instance address of the application-supplied callback 
function that will draw the string. For more information, see the description of 
the Windows OutputProc callback function below. 


If this parameter is NULL, the system uses the Windows TextOut function to 
draw the string, and /pData is assumed to be a long pointer to the character 
string to be output. 


[pData 
Specifies a far pointer to data to be passed to the output function. If JpfnOutput 
is NULL, /pData must be a long pointer to the string to be output. 


nCount 
Specifies the number of characters to be output. If this parameter is 0, 
GrayString calculates the length of the string (assuming that /pData is a 
pointer to the string). If nCount is —1 and the function pointed to by [pfnOutput 
returns 0, the image is shown but not dimmed. 


Specifies the logical x-coordinate of the starting position of the rectangle that 
encloses the string. 


Remarks 
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Specifies the logical y-coordinate of the starting position of the rectangle that 
encloses the string. 


nWidth 
Specifies the width (in logical units) of the rectangle that encloses the string. If 
nWidth is 0, GrayString calculates the width of the area, assuming /pData is a 
pointer to the string. 


nHeight 
Specifies the height (in logical units) of the rectangle that encloses the string. If 
nHeight is 0, GrayString calculates the height of the area, assuming /pData is 
a pointer to the string. 


Draws dimmed (gray) text at the given location by writing the text in a memory 
bitmap, dimming the bitmap, and then copying the bitmap to the display. The func- 
tion dims the text regardless of the selected brush and background. The 
GrayString member function uses the currently selected font. 


If IpFnOutput is NULL, GDI uses the Windows TextOut function, and /pData is 
assumed to be a far pointer to the character to be output. If the characters to be out- 
put cannot be handled by TextOut (for example, the string is stored as a bitmap), 
the application must supply its own output function. 


Also note that all callback functions must trap Foundation exceptions before re- 
turning to Windows, since exceptions cannot be thrown across callback boundar- 
ies. For more information about exceptions, see Chapter 12 in the Class Libraries 
User’s Guide. 


The callback function passed to GrayString must use the Pascal calling conven- 
tion, must be exported with __ export, and must be declared FAR. 


Callback Function 


BOOL FAR PASCAL __ export OutputFunc( HDC ADC, DWORD /[pData, 
int nCount ); 


OutputFunc is a placeholder for the application-supplied callback function name. 
The actual name must be exported as described in the “Remarks” above. The call- 
back function (OutputFunc) must draw an image relative to the coordinates (0,0) 
rather than (x, y). 
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Return Value 


See Also 


Syntax 


Parameters 


Parameter Description 


hDC Identifies a memory device context with a bitmap of at 
least the width and height specified by nWidth and nHeight 
to GrayString, respectively. 


[pData Points to the character string to be drawn. 


nCount Specifies the number of characters to output. 


Return Value 
The callback function’s return value must be nonzero to indicate success. Other- 
wise, it is 0. 


TRUE if the string is drawn, or FALSE if either the TextOut function or the 
application-supplied output function returned FALSE, or there was insufficient 
memory to create a memory bitmap for dimming. 


::GetSysColor, CDC::SetTextColor, CDC::TextOut, ::GrayString 


CDC::IntersectClipRect 


int IntersectClipRect( int x/, int y/, int x2, int y2 ); 


int IntersectClipRect( LPRECT [pRect ); 


xl 
Specifies the logical x-coordinate of the upper-left corner of the rectangle. 


yl 
Specifies the logical y-coordinate of the upper-left corner of the rectangle. 


x2 

Specifies the logical x-coordinate of the lower-right corner of the rectangle. 
y2 

Specifies the logical y-coordinate of the lower-right corner of the rectangle. 


lpRect 
Specifies the rectangle. You can pass either a CRect okie! or a pointer to a 
RECT structure for this parameter. 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


See Also 
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Creates a new clipping region by forming the intersection of the current region and 
the rectangle specified by x/, y/, x2, and y2. GDI clips all subsequent output to fit 
within the new boundary. 


The new clipping region’s type. It can be any one of the following values: 


Value Meaning 


COMPLEXREGION New clipping region has overlapping borders. 


ERROR Device context is not valid. 
NULLREGION New clipping region is empty. 
SIMPLEREGION New clipping region has no overlapping borders. 


::IntersectClipRect, CRect 


CDC::InvertRect 


void InvertRect( LPRECT /pRect ); 


[pRect 
Points to a RECT or CRect that contains the logical coordinates of the rec- 
tangle to be inverted. You can also pass a CRect object for this parameter. 


Inverts the contents of the given rectangle. On monochrome displays, the function 
makes white pixels black, and black pixels white. On color displays, the inversion 
depends on how colors are generated for the display. Calling InvertRect twice 
with the same rectangle restores the display to its previous colors. 


If the rectangle is empty, nothing is drawn. 


::InvertRect, CRect 
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Remarks 
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See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CDC::InvertRgn 
BOOL InvertRgn( CRgn* pR¢gn ); 


pkgn 
Identifies the region to be inverted. The coordinates for the region are specified 
in device units. 


Inverts the colors in the region specified by pRgn. On monochrome displays, the 
function makes white pixels black, and black pixels white. On color displays, the 
inversion depends on how the colors are generated for the display. 


TRUE if the function is successful; otherwise FALSE. 


CRegn, ::InvertRgen 


CDC::LineTo 


BOOL LineTo( int x, int y ); 
BOOL LineTo( POINT point ); 


x 
Specifies the logical x-coordinate of the endpoint for the line. 


Specifies the logical y-coordinate of the endpoint for the line. 


point | 
Specifies the endpoint for the line. You can pass either a POINT structure or a 
CPoint object for this parameter. 


Draws a line from the current position up to, but not including, the point specified 
by x and y (or point). The line is drawn with the selected pen. The current position 
is set to x,y or to point. 

TRUE if the line is drawn; otherwise FALSE. 


CDC::MoveTo, CDC::GetCurrentPosition, ::LineTo 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 
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CDC::LPtoDP 


void LPtoDP( LPPOINT /pPoints, int nCount = 1 ) const; 
void LPtoDP( LPRECT I/pRect ) const; 


lpPoints 
Points to an array of points. Each point in the array is a POINT structure or a 
CPoint object. 


nCount 
Specifies the number of points in the array. 


lpRect 
Points to a RECT structure or a CRect object. This parameter is used for the 
common case of mapping a rectangle from logical to device units. 


Converts logical points into device points. The function maps the coordinates of 
each point from GDI’s logical coordinate system into a device coordinate system. 
The conversion depends on the current mapping mode. 


::LPtoDP 


CDC::MoveTo 


CPoint MoveTo( int x, int y ); 


CPoint MoveTo( POINT point ); 


x 
Specifies the logical x-coordinate of the endpoint for the line. 


Specifies the logical y-coordinate of the endpoint for the line. 


point 
Specifies the endpoint for the line. You can pass either a POINT structure or a 
CPoint object for this parameter. 
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Remarks 
Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Moves the current position to the point specified by x and y (or by point). 
The x- and y-coordinates of the previous position as a CPoint object. 


CDC::GetCurrentPosition, CDC::LineTo, :;:MoveTo 


CDC::OffsetClipRgn 
int OffsetClipRgn( int x, int y )3 
int OffsetClipRgen( SIZE size ); 


x 
Specifies the number of logical units to move left or right. 


Specifies the number of logical units to move up or down. 
size 
Specifies the amount to offset. 


Moves the clipping region of the given device by the specified offsets. The func- 
tion moves the region x units along the x-axis and y units along the y-axis. 


The new region’s type. It can be any one of the following values: 


Value Meaning 

COMPLEXREGION Clipping region has overlapping borders. 
ERROR Device context is not valid. 
NULLREGION Clipping region is empty. 
SIMPLEREGION Clipping region has no overlapping borders. 


::OffsetClipRgn 
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Parameters 
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See Also 
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Return Value 


See Also 
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CDC::OffsetViewportOrg 


CPoint Offset ViewportOrg( int nWidth, int nHeight ); 


nWidth 
Specifies the number of device units to add to the current origin’s x-coordinate. 


nHeight 
Specifies the number of device units to add to the current origin’s y-coordinate. 


Modifies the viewport origin relative to the coordinates of the current viewport 
origin. 


The previous viewport origin (in device coordinates) as a CPoint object. 


CDC::GetViewportOrg, CDC::OffsetWindowOrg, CDC::SetViewportOrg, 
::Offset ViewportOrg 


CDC::0ffsetWindowOrg 


CPoint OffsetWindowOrg( int nWidth, int nHeight ); 


nWidth 
Specifies the number of logical units to add to the current origin’s x-coordinate. 


nHeight 
Specifies the number of logical units to add to the current origin’s y-coordinate. 


Modifies the window origin relative to the coordinates of the current window 
origin. 


The previous window origin (in logical coordinates) as a CPoint object. 


CDC::GetWindowOrg, CDC::Offset ViewportOrg, CDC::SetWindowOrg, 
::OffsetWindowOrg 
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Syntax 


Parameters 


Remarks 
Return Value 


See Also 


Syntax 


Parameters 


CDC::PaintRgn 
BOOL PaintRen( CRgn* pRen ); 


pRegn 
Identifies the region to be filled. The coordinates for the given region are 
specified in device units. 


Fills the region specified by pRgn with the selected brush. 
TRUE if the function is successful; otherwise FALSE. 


CBrush, CDC::SelectObject, CDC::FillRgn, ::PaintRgn 


CDC::PatBit 


BOOL PatBit( int x, int y, int nWidth, int nHeight, DWORD dwkop ); 


x 
Specifies the logical x-coordinate of the upper-left corner of the rectangle that 
is to receive the pattern. 


Specifies the logical y-coordinate of the upper-left corner of the rectangle that 
is to receive the pattern. 


nWidth 
Specifies the width (in logical units) of the rectangle that is to receive the 
pattern. 


nHeight | 
Specifies the height (in logical units) of the rectangle that is to receive the 
pattern. 


dwRop 
Specifies the raster-operation code. Raster-operation codes (ROPs) define how 
GDI combines colors in output operations that involve a current brush, a 
possible source bitmap, and a destination bitmap. This parameter may be one of 
the following values: 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 
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Value Meaning 
PATCOPY Copies pattern to destination bitmap. 


PATINVERT Combines destination bitmap with pattern using the 
Boolean OR operator. 


DSTINVERT Inverts the destination bitmap. 
BLACKNESS Turns all output black. 
WHITENESS Turns all output white. 


Creates a bit pattern on the specified device. The pattern is a combination of the 
selected brush and the pattern already on the device. The raster-operation code 
specified by dwRop defines how the patterns are to be combined. The values of 
dwkop for this function are a limited subset of the full 256 ternary raster-operation 
codes; in particular, an operation code that refers to a source cannot be used. Not 
all devices support the PatBlt function. 


For more information, see the RC_BITBLT capability under the GetDeviceCaps 
member function. 


TRUE if the bit pattern is drawn; otherwise FALSE. 


CDC::GetDeviceCaps, ::PatBlt 


CDC::Pie 
BOOL Pie( int x/, int y/, int x2, int y2, int x3, int y3, int x4, int y4 ); 


BOOL Pie( LPRECT /pRect, POINT ptStart, POINT ptEnd ); 


xl 
Specifies the x-coordinate of the upper-left corner of the bounding rectangle (in 
logical units). 

yl 
Specifies the y-coordinate of the upper-left corner of the bounding rectangle (in 
logical units). 

x2 


Specifies the x-coordinate of the lower-right corner of the bounding rectangle 
(in logical units). 
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Remarks 


Return Value 


See Also 


y2 
Specifies the y-coordinate of the lower-right corner of the bounding rectangle 
(in logical units). 


x3 
Specifies the x-coordinate of the arc’s starting point (in logical units). This 
point does not have to lie exactly on the arc. 


y3 
Specifies the y-coordinate of the arc’s starting point (in logical units). This 
point does not have to lie exactly on the arc. 


x4 
Specifies the x-coordinate of the arc’s endpoint (in logical units). This point 
does not have to lie exactly on the arc. 


y4 
Specifies the y-coordinate of the arc’s endpoint (in logical units). This point 
does not have to lie exactly on the arc. 


lpRect 
Specifies the bounding rectangle. You can pass either a CRect object or a 
pointer to a RECT structure for this parameter. 


ptStart 
Specifies the starting point of the arc. This point does not have to lie exactly on 
the arc. You can pass either a POINT structure or a CPoint object for this para- 
meter. 


ptEnd 
Specifies the endpoint of the arc. This point does not have to lie exactly on the 
arc. You can pass either a POINT structure or a CPoint object for this parame- 
ter. 


Draws a pie-shaped wedge by drawing an elliptical arc whose center and two end- 
points are joined by lines. The center of the arc is the center of the bounding rec- 
tangle specified by x/, y/, x2, and y2 (or by [pRect). The starting and ending 
points of the arc are specified by x3, y3, x4, and y4 (or by ptStart and ptEnd). The 
arc is drawn with the selected pen, moving in a counterclockwise direction. Two 
additional lines are drawn from each endpoint to the arc’s center. The pie-shaped 
area is filled with the current brush. If x3 equals x4 and y3 equals y4, the result is 
an ellipse with a single line from the center of the ellipse to the point (x3, y3), or 
(x4, y4). 


TRUE if the function is successful; otherwise FALSE. 


CDC::Chord, ::Pie 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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See Also 
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CDC::PlayMetaFile 


BOOL PlayMetaFile( HANDLE AMF ); 


hMF 
Identifies the metafile. 


Plays the contents of the specified metafile on the given device. The metafile can 
be played any number of times. 


TRUE if the function is successful; otherwise FALSE. 


::PlayMetaFile 


CDC::Polygon 


BOOL Polygon( LPPOINT /pPoints, int nCount ); 


[pPoints 
Points to an array of points that specify the vertices of the polygon. Each point 
in the array is a POINT structure or a CPoint object. 


nCount 
Specifies the number of vertices given in the array. 


Draws a polygon consisting of two or more points (vertices) connected by lines. 
The system closes the polygon automatically, if necessary, by drawing a line from 
the last vertex to the first. 


The current polygon-filling mode can be retrieved or set by using 
GetPolyFillMode and SetPolyFillMode. 


TRUE if the function is successful; otherwise FALSE. 


CDC::GetPolyFillMode, ::PolyLine, CDC::PolyPolygon, 
CDC::SetPolyFillMode, ::Polygon 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


CDC::Polyline 
BOOL Polyline( LPPOINT [pPoints, int nCount ); 


lpPoints 
Points to an array of points to be connected. 


nCount 
Specifies the number of points in the array. This value must be at least 2. 


Draws a set of line segments, connecting the points specified by /pPoints. The 
lines are drawn from the first point through subsequent points, using the current 
pen. Unlike LineTo, the Polyline function neither uses nor updates the current 
position. 


TRUE if the function is successful; otherwise FALSE. 


CDC::LineTo, CDC::Polygon, ::PolyLine 


CDC::PolyPolygon 


BOOL PolyPolygon( LPPOINT [pPoints, LPINT /pPolyCounts, int nCount ); 


lpPoints 
Points to an array of POINT structures or CPoint objects that define the ver- 
tices of the polygons. 


[pPolyCounts 
Points to an array of integers, each of which specifies the number of points in 
one of the polygons in the /pPoints array. 


nCount 
The number of entries in the JpPolyCounts array. This number specifies the 
number of polygons to be drawn. This value must be at least 2. 


Creates two or more polygons that are filled using the current polygon-filling 
mode. The polygons may be disjoint or they may overlap. 


Each polygon specified in a call to the PolyPolygon function must be closed. Un- 
like polygons created by the Polygon member function of CDC, the polygons 
created by PolyPolygon are not closed automatically. 


Return Value 


See Also 
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Parameters 


Remarks 


Return Value 


See Also 
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The function creates two or more polygons. To create a single polygon, an applica- 
tion should use the Polygon member function. 


The current polygon-filling mode can be retrieved or set by using the 
GetPolyFillMode and SetPolyFillMode member functions. 


TRUE if the function is successful; otherwise FALSE. 


CDC::GetPolyFillMode, CDC::Polygon, CDC::Polyline, 
CDC::SetPolyFillMode, ::PolyPolygon 


CDC::PtVisible 


BOOL PtVisible( int x, int y ) const; 
BOOL PtVisible( POINT point ) const; 


x 
Specifies the logical x-coordinate of the point. 


Specifies the logical y-coordinate of the point. 


point 
Specifies the point to check in logical coordinates. You can pass either a 
POINT structure or a CPoint object for this parameter. 


Specifies whether the given point is within the clipping region of the device 
context. 


TRUE if the specified point is within the clipping region; otherwise FALSE. 


CPoint, ::PtVisible 
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Remarks 
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See Also 
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CDC::RealizePalette 


UINT RealizePaletteQ; 


Takes entries in the logical palette currently selected into a device context and 
maps them to the system palette. 


A logical color palette acts as a buffer between color-intensive applications and 
the system, allowing an application to use as many colors as needed without inter- 
fering with its own color display, or with colors displayed by other windows. 


When a window has input focus and calls the function, Windows ensures that it 
will display all the colors it requests, up to the maximum number simultaneously 
available on the display, and displays colors not found in the window’s palette by 
matching them to available colors. 


In addition, Windows matches the colors requested by inactive windows that call 
the function as closely as possible to the available colors. This significantly re- 
duces undesirable changes in the colors displayed in inactive windows. 


Specifies how many entries in the logical palette were mapped to different entries 
in the system palette. This represents the number of entries that this function re- 
mapped to accommodate changes in the system palette since the logical palette 
was last realized. 


CPalette, ::RealizePalette 


CDC::Rectangle 


BOOL Rectangle( int x/, int y/, int x2, int y2 ); 
BOOL Rectangle( LPRECT /pRect ); 


xl 
Specifies the x-coordinate of the upper-left corner of the rectangle (in logical 
units). 

yl 
Specifies the y-coordinate of the upper-left corner of the rectangle (in logical 
units). 


Remarks 


Return Value 


See Also 
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See Also 
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x2 
Specifies the x-coordinate of the lower-right corner of the rectangle (in logical 
units). 


y2 
Specifies the y-coordinate of the lower-right corner of the rectangle (in logical 
units). 


lpRect 
Specifies the rectangle in logical units. You can pass either a CRect object or a 
pointer to a RECT structure for this parameter. 


Draws a rectangle using the current pen. The interior of the rectangle is filled 
using the current brush. 


TRUE if the function is successful; otherwise FALSE. 


::Rectangle, ::PolyLine, CDC::RoundRect 


CDC::RectVisible 


BOOL RectVisible( LPRECT /pRect ) const; 
[pRect 
Points to a RECT structure or a CRect object that contains the logical coordi- 


nates of the specified rectangle. 


Determines whether any part of the given rectangle lies within the clipping region 
of the current display context. 


TRUE if some portion of the given rectangle lies within the clipping region; other- 
wise FALSE. 


::RectVisible 
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CDC::RestoreDC 


Syntax BOOL RestoreDC( int nSavedDC ); 


Parameters nSavedDC 
Specifies the device context to be restored. It must be a value returned by a pre- 
vious SaveDC function call. If ~SavedDC is —1, the most recent device context 
saved is restored. 


Remarks Restores the Windows device context to the previous state identified by 
nSavedDC. RestoreDC restores the device context by copying state information 
saved on the Windows internal context stack by earlier calls to the SaveDC mem- 
ber function. 


The Windows internal context stack can contain the state information for several 
device contexts. If the context specified by nSavedDC is not at the top of the stack, 
RestoreDC deletes any state information between the device context specified by 
nSavedDC and the top of the stack. The deleted information is lost. 


Return Value TRUE if the specified context was restored; otherwise FALSE. 


See Also CDC::SaveDC, ::RestoreDC 


CDC::RoundRect 


Syntax BOOL RoundRect( int x/, int y/, int x2, int y2, int x3, int y3 ); 
BOOL RoundRect( LPRECT /pRect, POINT point ); 


Parameters x 
Specifies the x-coordinate of the upper-left corner of the rectangle (in logical 
units). 
yl 
Specifies the y-coordinate of the upper-left corner of the rectangle (in logical 
units). 


XZ 
Specifies the x-coordinate of the lower-right corner of the rectangle (in logical 
units). 


Remarks 


Return Value 


See Also 
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Remarks 
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y2 
Specifies the y-coordinate of the lower-right corner of the rectangle (in logical 
units). 


x3 
Specifies the width of the ellipse used to draw the rounded corners (in logical 
units). 


y3 
Specifies the height of the ellipse used to draw the rounded corners (in logical 
units). 


lpRect 
Specifies the bounding rectangle in logical units. You can pass either a CRect 
object or a pointer to a RECT structure for this parameter. 

point 
The x-coordinate of point specifies the width of the ellipse to draw the rounded 
corners (in logical units). The y-coordinate of point specifies the height of the 
ellipse to draw the rounded corners (in logical units). You can pass either a 
POINT structure or a CPoint object for this parameter. 


Draws a rectangle with rounded corners, using the current pen. The interior of the 
rectangle is filled using the current brush. 


TRUE if the function is successful; otherwise FALSE. 


CDC::Rectangle, :: RoundRect 


CDC::SaveDC 


int SaveDC() const; 


Saves the current state of the device context by copying state information (such as 
clipping region, selected objects, and mapping mode) to a context stack main- 
tained by Windows. The saved device context can later be restored by using 
RestoreDC. 


SaveDC can be used any number of times to save any number of device-context 
States. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Specifies the saved device context. It is 0 if an error occurs. This return value is 
used on a subsequent call to RestoreDC to restore the device context state. 


CDC::RestoreDC, ::SaveDC 


CDC::ScaleViewportExt 


CSize Scale ViewportExt( int xNum, int xDenom, int yNum, int yDenom ); 


xNum 
Specifies the amount by which to multiply the current x-extent. 


xDenom 
Specifies the amount by which to divide the current x-extent. 


yNum 
Specifies the amount by which to multiply the current y-extent. 


yDenom 
Specifies the amount by which to divide the current y-extent. 


Modifies the viewport extents relative to the current values. The formulas are writ- 
ten as follows: 


XNewVE 
yNewVE 


( xOIdVE * xNum ) / xDenom 
( yOIdVE * yNum ) / yDenom 


The new extent is calculated by multiplying the current extents by the given 
numerator and then dividing by the given denominator. 


The previous viewport extents (in device units) as a CSize object. 


::ScaleViewportExt 
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CDC::ScaleWindowExt 


Syntax CSize ScaleWindowExt( int xNum, int xDenom, int yNum, int yDenom ); 


Parameters xNum 
Specifies the amount by which to multiply the current x-extent. 


xDenom 
Specifies the amount by which to divide the current x-extent. 


yNum 
Specifies the amount by which to multiply the current y-extent. 


yDenom 
Specifies the amount by which to divide the current y-extent. 


Remarks Modifies the window extents relative to the current values. The formulas are writ- 
ten as follows: 


xNewVE 
yNewVE 


( xOIdVE * xNum ) / xDenom 
( yOldVE * yNum ) / yDenom 


The new extent is calculated by multiplying the current extents by the given 
numerator and then dividing by the given denominator. 


Return Value The previous window extents (in logical units) as a CSize object. 


See Also ::ScaleWindowExt 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CDC::ScrollDC 


BOOL ScrollDC( int dx, int dy, LPRECT [pRectScroll, LPRECT [pRectClip, 
CRegn* pRenUpdate, LPRECT [pRectUpdate ); 


dx 
Specifies the number of horizontal scroll units. 


dy 
Specifies the number of vertical scroll units. 


lpRectScroll 
Points to the RECT structure or CRect object that contains the coordinates of 
the scrolling rectangle. 


lpRectClip 
Points to the RECT structure or CRect object that contains the coordinates of 
the clipping rectangle. When this rectangle is smaller than the original pointed 
to by /pRectScroll, scrolling occurs only in the smaller rectangle. 


pRgnUpdate 
Identifies the region uncovered by the scrolling process. The ScrolIDC function 
defines this region; it is not necessarily a rectangle. 


[pRectUpdate 
Points to the RECT structure or CRect object that, upon return, contains the 
coordinates of the rectangle that bounds the scrolling update region. This is the 
largest rectangular area that requires repainting. 


Scrolls a rectangle of bits horizontally and vertically. The /pRectScroll parameter 
describes the rectangle to be scrolled, dx specifies the number of units to be 
scrolled horizontally, and dy specifies the number of units to be scrolled vertically. 


If IpRectUpdate is NULL, Windows does not compute the update rectangle. If 
both pRenUpdate and I[pRectUpdate are NULL, Windows does not compute the 
update region. If pRenUpdate is not NULL, Windows assumes that it contains a 
valid region pointer to the region uncovered by the scrolling process (defined by 
the ScrollIDC member function). An application should use the ScrollWindow 
member function of class CWnd when it is necessary to scroll the entire client 
area of a window. Otherwise, it should use ScrolIDC. 


TRUE if scrolling is executed; otherwise FALSE. 


CWnd::ScrollWindow, ::ScrolIDC, CRgn 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CDC::SelectClipRgn 


int SelectClipRgn( CRgn* pRen ); 


pkgn 
Identifies the region to be selected. 


Selects the given region as the current clipping region for the specified device con- 
text. Only a copy of the selected region is used. The region itself can be selected 
for any number of other device contexts, or it can be deleted. 


The function assumes that the coordinates for the given region are specified in dev- 
ice units. Some printer devices support graphics at lower resolutions than text out- 
put to increase speed, but at the expense of quality. These devices scale 
coordinates for graphics so that one graphics device point corresponds to two or 
four true device points. This scaling factor affects clipping. If a region will be used 
to clip graphics, its coordinates must be divided down by the scaling factor. If the 
region will be used to clip text, no scaling adjustment is needed. The scaling factor 
is determined by using the GETSCALINGFACTOR printer escape. 


The region’s type. It can be any one of the following values: 


Value Meaning 

COMPLEXREGION New clipping region has overlapping borders. 
ERROR Device context or region handle is not valid. 
NULLREGION New clipping region is empty. 
SIMPLEREGION New clipping region has no overlapping borders. 


CDC::Escape, CRgn, ::SelectClipRgn 


232 CDC::SelectObject 


Syntax 


Parameters 


Remarks 


CDC::SelectObject 


CGdiObject* SelectObject( CGdiObject* pObject ); 
CPen* SelectObject( CPen* pPen ); 

CBrush* SelectObject( CBrush* pBrush ); 

CFont* SelectObject( CFont* pFont ); 

CBitmap* SelectObject( CBitmap* pBitmap ); 


int SelectObject( CRgn* pRen ); 


pObject 
Identifies the object to be selected. 


Note that this general version of the SelectObject member function does not 
work for regions. To select regions, see the version of SelectObject in the next 
group that is specialized for regions. 


pPen 
A pointer to a CPen object to be selected. 


pBrush 
A pointer to a CBrush object to be selected. 


pFont 
A pointer to a CFont object to be selected. 


pBitmap 
A pointer to a CBitmap object to be selected. 


pRgn 
A pointer to a CRgn object to be selected. 


Selects an object into the current device context. Class CDC provides a general 
version of SelectObject and five versions specialized for particular kinds of GDI 
objects, including pens, brushes, fonts, bitmaps, and regions. 


The newly selected object replaces the previous object of the same type. For ex- 
ample, if pObject of the general version of SelectObject points to a CPen object, 
the function replaces the current pen with the pen specified by pObject. 


Note that class CMetaFileDC overrides the SelectObject member function. The 
CMetaFileDC class is derived from class CDC specifically for use with meta- 
files. For information on object selection in metafiles, see the CMetaFileDC class. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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An application can select a bitmap into memory device contexts only, and into 
only one memory device context at a time. The format of the bitmap must either 
be monochrome or compatible with the specified device; if it is not, SelectObject 
returns an error. 


A pointer to a CGdiObject object or to an object of one of the classes derived 
from CGdiObject, such as CPen, depending on which version of the function 
used. The object pointed to is being replaced by the object specified by the func- 
tion’s parameter. It is NULL if there is an error. 


For the version of the member function that takes a region parameter, pRgn, the re- 
turn value is one of the following: 


Value Meaning 

COMPLEXREGION New clipping region has overlapping borders. 
ERROR Device context or region handle is not valid. 
NULLREGION New clipping region is empty. 
SIMPLEREGION New clipping region has no overlapping borders. 


CGdiObject::DeleteObject, CDC::SelectClipRgn, CDC::SelectPalette, 
::SelectObject 


CDC::SelectPalette 


CPalette* SelectPalette( CPalette* pPalette, BOOL bForceBackground ); 


pPalette 
Identifies the logical palette to be selected. This palette must already have been 
created with the CPalette member function CreatePalette. 


bForceBackground 
Specifies whether the logical palette is forced to be a background palette. If 
bForceBackground is TRUE, the selected palette is always a background 
palette, regardless of whether the window has input focus. If 
bForceBackground is FALSE, the logical palette is a foreground palette when 
the window has input focus. 


Selects the logical palette specified by pPalette as the selected palette object of the 
device context. The new palette becomes the palette object used by GDI to control 
colors displayed in the device context and replaces the previous palette. 
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Return Value 


See Also 


Syntax 


Parameters 


An application can select a logical palette into more than one device context. How- 
ever, changes to a logical palette will affect all device contexts for which it is 
selected. If an application selects a palette object into more than one device con- 
text, the device contexts must all belong to the same physical device (such as a dis- 


play or printer). 


A pointer to a CPalette object, identifying the logical palette replaced by the 
palette specified by pPalette. It is NULL if there is an error. 


CPalette, ::SelectPalette 


CDC::SelectStockObject 


CGdiObject* SelectStockObject( int n/ndex ); 


nindex 


Specifies the kind of stock object desired. It can be one of the following values: 


Value 
BLACK_BRUSH 
DKGRAY_BRUSH 
GRAY_ BRUSH 
HOLLOW_BRUSH 
LTGRAY_BRUSH 
NULL_ BRUSH 
WHITE_BRUSH 
BLACK_PEN 
NULL_PEN 
WHITE_PEN 

ANSL FIXED_FONT 
ANSI VAR_ FONT 
DEVICE_DEFAULT_FONT 
OEM_FIXED_FONT 


Meaning 

Black brush. 

Dark gray brush. 

Gray brush. 

Hollow brush. 

Light gray brush. 

Null brush. 

White brush. 

Black pen. 

Null pen. 

White pen. 

ANSI fixed system font. 
ANSI variable system font. 
Device-dependent font. 
OEM-dependent fixed font. 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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Value Meaning 


SYSTEM_FONT The system font. By default, Windows 
uses the system font to draw menus, 
dialog-box controls, and other text. In 
Windows versions 3.0 and later, the 
system font is proportional width; 
earlier versions of Windows use a 
fixed-width system font. 


SYSTEM_FIXED_FONT The fixed-width system font used in 
Windows prior to version 3.0. This 
object is available for compatibility 
with earlier versions of Windows. 


DEFAULT_PALETTE Default color palette. This palette 
consists of the 20 static colors in the 
system palette. 


Selects a CGdiObject object that corresponds to one of the predefined stock pens, 
brushes, or fonts. 


A pointer to the CGdiObject object that was replaced if the function is successful. 
The actual object pointed to is a CPen, CBrush, or CF ont object. If the call is un- 
successful, the return value is NULL. 


CGdiObject::GetObject 


CDC::SetAbortProc 


int SetAbortProc( short (FAR PASCAL EXPORT* Ipfn )( HDC, short ) ); 


lpfn 
A pointer to the abort function to install as the abort procedure. For more about 
this callback function, see below. 


Installs the abort procedure for the print job. 


If an application is to allow the print job to be canceled during spooling, it must 
set the abort function before the print job is started with the StartDoc member 
function or the STARTDOC escape, which are equivalent. Print Manager calls 
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the abort function during spooling to allow the application to cancel the print job 
or to process out-of-disk-space conditions. If no abort function is set, the print job 
will fail if there is not enough disk space for spooling. 


Note that new features of Microsoft C/C++ let you use an ordinary function as the 
function passed to SetAbortProc. The address passed to EnumObjects is a FAR 
pointer to a function exported with __ export and with the Pascal calling conven- 
tion. In protect-mode applications, you do not have to create this function with the 
Windows MakeProcInstance function or free the function after use with Free- 
ProcInstance. 


You also do not have to export the function name in an EXPORTS statement in 
your application’s module-definition file. You can instead use the __ export func- 
tion modifier, as in 


Short FAR PASCAL __ export AFunction( HDC, short ); 


to cause the compiler to emit the proper export record for export by name without 
aliasing. This works for most needs. For some special cases, such as exporting a 
function by ordinal or aliasing the export, you still need to use an EXPORTS 
statement in a module-definition file. 


For compiling Foundation programs, you’ll normally use the /GA and /GEs com- 
piler options. The /Gw compiler option is not used with the Foundation classes. (If 
you do use MakeProcInstance, you will need to explicitly cast the returned func- 
tion pointer from FARPROC to the type needed in this API.) Callback registra- 
tion interfaces are now type-safe (you must pass in a function pointer that points to 
the right kind of function for the specific callback). 


Also note that all callback functions must trap Foundation exceptions before re- 
turning to Windows, since exceptions cannot be thrown across callback boundar- 
ies. For more information about exceptions, see Chapter 12 in the Class Libraries 
User’s Guide. 


Callback Function 


The callback function must use the Pascal calling convention, must be exported 
with __ export, and must be declared FAR. 


short FAR PASCAL __ export AbortFunc( HDC hPr, short code ); 


Return Value 
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The name AbortFunc 1s a placeholder for the application-supplied function name. 
The actual name must be exported as described in the “Remarks” section above. 


Parameter 


hPr 


code 


Return Value 


Description 


Identifies the device context. 


Specifies whether an error has occurred. It is O if 
no error has occurred. It is SP_OUTOFDISK if 
Print Manager is currently out of disk space and 
more disk space will become available if the 
application waits. If code is SP_OUTOFDISK, 
the application does not have to abort the print 
job. If it does not, it must yield to Print Manager 
by calling the Peek Message or GetMessage 
function. 


The return value of the abort-handler function is nonzero if the print job 1s to con- 


tinue, and 0 if it is canceled. 


Specifies the outcome of the SetAbortProc function. Some of the following 
values are more probable than others, but all are possible. 


Value 


SP_ERROR 
SP_OUTOFDISK 


SP_OUTOFMEMORY 
SP_USERABORT 


Meaning 


General error. 


Not enough disk space is currently available for 
spooling, and no more space will become 
available. 


Not enough memory is available for spooling. 


User terminated the job through the Print 
Manager. 
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CDC::SetBkColor 


Syntax DWORD SetBkColor( DWORD crColor ); 


Parameters crColor 
Specifies the new background color. 


Remarks Sets the current background color to the specified color. If the background mode is 
OPAQUE, the system uses the background color to fill the gaps in styled lines, 
the gaps between hatched lines in brushes, and the background in character cells. 
The system also uses the background color when converting bitmaps between 
color and monochrome device contexts. 


If the device cannot represent the specified color, the system sets the background 
color to the nearest physical color. 


Return Value The previous background color as an RGB color value. If an error occurs, the re- 
turn value is Ox80000000. 


See Also CDC::GetBkColor, CDC::GetBkMode, CDC::SetBkMode, ::SetBkColor 


CDC::SetBkMode 


Syntax int SetBkMode( int nBkMode ); 
Parameters nBkMode 
Specifies the background mode. This parameter can be either of the following 
values: 
Value Meaning 
OPAQUE Background is filled with the current background 
color before the text, hatched brush, or pen 1s 
drawn. 


TRANSPARENT Background is not changed before drawing. 


CDC::SetBrushOrg = 239 


Remarks Sets the background mode. The background mode defines whether the system re- 
moves existing background colors on the drawing surface before drawing text, 
hatched brushes, or any pen style that is not a solid line. 


Return Value The previous background mode. It can be either OPAQUE or TRANSPARENT. 


See Also CDC::GetBkColor, CDC::GetBkMode, CDC::SetBkColor, ::SetBkMode 


CDC::SetBrushOrg 


Syntax CPoint SetBrushOrg( int x, int y ); 
CPoint SetBrushOrg( POINT point ); 


Parameters x 
Specifies the x-coordinate (in device units) of the new origin. This value must 
be in the range 0-7. 


Specifies the y-coordinate (in device units) of the new origin. This value must 
be in the range 0-7. 

point 
Specifies the x- and y-coordinate of the new origin. Each value must be in the 
range 0-7. You can pass either a POINT structure or a CPoint object for this 
parameter. 


Remarks Specifies the origin that GDI will assign to the next brush that an application 
selects into a device context. 


Do not use SetBrushOrg with stock CBrush objects. 


Return Value The previous origin of the brush in device units (which are relative to the origin of 
the desktop window). 
See Also CDC::GetBrushOrg, CDC::SelectObject, CGdiObject::UnrealizeObject, 


::SetBrushOrg 
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CDC::SetMapMode 


int SetMapMode( int nMapMode ); 


Syntax 


Parameters nMapMode 


Specifies the new mapping mode. It can be any one of the following values: 


Value 
MM_ ANISOTROPIC 


MM_HIENGLISH 


MM_HIMETRIC 


MM_ ISOTROPIC 


MM_LOENGLISH 


MM_LOMETRIC 


MM_ TEXT 


MM_TWIPS 


Remarks 


Meaning 


Logical units are mapped to arbitrary units with 
arbitrarily scaled axes. The SetWindowExt and 
SetViewportExt member functions of class 
CDC must be used to specify the desired units, 
orientation, and scaling. 


Each logical unit 1s mapped to 0.001 inch. 
Positive x is to the right; positive y is up. 


Each logical unit is mapped to 0.01 millimeter. 
Positive x is to the right; positive y is up. 


Logical units are mapped to arbitrary units with 
equally scaled axes; that is, one unit along the x- 
axis 1S equal to one unit along the y-axis. The 
SetWindowExt and SetViewportExt member 
functions of class CDC must be used to specify 
the desired units and the orientation of the axes. 
GDI makes adjustments as necessary to ensure 
that the x and y units remain the same size. 


Each logical unit is mapped to 0.01 inch. 
Positive x is to the right; positive y is up. 

Each logical unit is mapped to 0.1 millimeter. 
Positive x is to the right; positive y is up. 

Each logical unit 1s mapped to one device pixel. 
Positive x is to the right; positive y is down. 


Each logical unit is mapped to one-twentieth of 
a printer’s point (1/1440 inch). Positive x is to 
the right; positive y is up. 


Sets the mapping mode. The mapping mode defines the unit of measure used to 


transform logical units into device units, and also defines the orientation of the 


device’s x- and y-axes. GDI uses the mapping mode to convert logical coordinates 


into the appropriate device coordinates. The MM_ TEXT mode allows applica- 
tions to work in device pixels, whose size varies from device to device. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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The MM_HIENGLISH, MM_HIMETRIC, MM_LOENGLISH, 
MM_LOMETRIC, and MM_TWIPS modes are useful for applications that 
need to draw in physically meaningful units (such as inches or millimeters). The 
MM_ISOTROPIC mode ensures a 1:1 aspect ratio, which is useful when it is im- 
portant to preserve the exact shape of an image. The MM_ ANISOTROPIC 
mode allows the x- and y-coordinates to be adjusted independently. 


The previous mapping mode. 


CDC::SetViewportExt, CDC::SetWindowExt, ::SetMapMode 


CDC::SetMapperFlags 


DWORD SetMapperFlags( DWORD dwFlag ); 


dwFlag 
Specifies whether the font mapper attempts to match a font’s aspect height and 
width to the device. When the first bit 1s set to 1, the mapper will only select 
fonts whose x-aspect and y-aspect exactly match those of the specified device. 


Alters the algorithm that the font mapper uses when it maps logical fonts to physi- 
cal fonts. When the first bit of dwFlag is set to 1, the mapper will only select fonts 
whose x-aspect and y-aspect exactly match those of the specified device. If no 
fonts exist with a matching aspect height and width, GDI chooses an aspect height 
and width and selects fonts with aspect heights and widths that match the one 
chosen by GDI. 


The remaining bits of dwFlag must be 0. 
The previous value of the font-mapper flag. 


::SetMapperFlags 
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syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


CDC::SetPixel 


DWORD SetPixel( int x, int y, DWORD crColor ); 
DWORD SetPixel( POINT point, DWORD crColor ); 


x 
Specifies the logical x-coordinate of the point to be set. 


Specifies the logical y-coordinate of the point to be set. 


crColor 
Specifies the color used to paint the point. 

point 
Specifies the logical x- and y-coordinates of the point to be set. You can pass 
either a POINT structure or a CPoint object for this parameter. 


Sets the pixel at the point specified to the closest approximation of the color 
specified by crColor. The point must be in the clipping region. If the point is not 
in the clipping region, the function is ignored. 


Not all devices support the function. For more information, see the RC_BITBLT 
capability in the GetDeviceCaps member function. 


An RGB color value for the color that the point is actually painted. This value can 
be different than that specified by crColor if an approximation of that color is 
used. If the function fails (if the point is outside the clipping region), the return 
value is —1. 


CDC::GetDeviceCaps, CDC::GetPixel, ::SetPixel 


CDC::SetPolyFillMode 


int SetPolyFillMode( int nPolyFillMode ); 


nPolyFillMode 
Specifies the new filling mode. This value may be either ALTERNATE or 
WINDING. 


Sets the polygon-filling mode. 


Return Value 


See Also 


Syntax 


Parameters 
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When the polygon-filling mode is ALTERNATE, the system fills the area be- 
tween odd-numbered and even-numbered polygon sides on each scan line. That is, 
the system fills the area between the first and second side, between the third and 
fourth side, and so on. 


When the polygon-filling mode is WINDING, the system uses the direction in 
which a figure was drawn to determine whether to fill an area. Each line segment 
in a polygon is drawn in either a clockwise or a counterclockwise direction. When- 
ever an imaginary line drawn from an enclosed area to the outside of a figure 
passes through a clockwise line segment, a count is incremented. When the line 
passes through a counterclockwise line segment, the count is decremented. The 
area 1s filled if the count is nonzero when the line reaches the outside of the figure. 


The previous filling mode. It is 0 if there is an error. 


CDC::GetPolyFillMode, CDC::PolyPolygon, ::SetPolyFillMode 


CDC::SetROP2 


int SetROP2( int nDrawMode ); 


nDrawMode 
Specifies the new drawing mode. It can be any one of the following values: 
Value Meaning 
R2_ BLACK Pixel is always black. 
R2_ WHITE Pixel is always white. 
R2_NOP Pixel remains unchanged. 
R2_NOT Pixel is the inverse of the display color. 
R2_COPYPEN Pixel is the pen color. 


R2_NOTCOPYPEN Pixel is the inverse of the pen color. 


R2_MERGEPENNOT Pixel is a combination of the pen color and the 
inverse of the display color. 


R2_ MASKPENNOT Pixel is a combination of the colors common to 
both the pen and the inverse of the display. 


R2_MERGENOTPEN __ Pixel is a combination of the display color and 
the inverse of the pen color. 
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Value Meaning 


R2_ MASKNOTPEN Pixel is a combination of the colors common to 
both the display and the inverse of the pen. 


R2_ MERGEPEN Pixel is a combination of the pen color and the 
display color. 

R2_ NOTMERGEPEN Pixel is the inverse of the R2- MERGEPEN 
color. 

R2_ MASKPEN Pixel is a combination of the colors common to 


both the pen and the display. 
R2_ NOTMASKPEN Pixel is the inverse of the R2_-MASKPEN 


color. 
R2_ XORPEN Pixel is a combination of the colors in the pen 
and in the display, but not in both. 
R2_NOTXORPEN Pixel is the inverse of the R2_ XORPEN color. 
Remarks Sets the current drawing mode. The drawing mode specifies how the colors of the 


pen and the interior of filled objects are combined with the color already on the dis- 
play surface. 


Drawing modes are binary raster-operation codes, representing all possible 
Boolean functions of two variables, using the binary operations AND, OR, and 
XOR (exclusive OR), and the unary operation NOT. 


Return Value The previous drawing mode. It can be any one of the values given in the Windows 
Software Development Kit documentation. 


See Also CDC::GetDeviceCaps, CDC::GetROP2, ::SetROP2 


Syntax 


Parameters 


Remarks 


See Also 
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CDC::SetStretchBltMode 


int SetStretchBltMode( int nStretchMode ); 


nStretchMode 


Specifies the new bitmap-stretching mode. It can be one of the following values: 


Value 
BLACKONWHITE 


COLORONCOLOR 


WHITEONBLACK 


Meaning 


Uses the AND operator to combine eliminated 
lines with the remaining lines. This mode 
preserves black pixels at the expense of colored 
or white pixels. 


Deletes the eliminated lines. Information in the 
eliminated lines is not preserved. 


Uses the OR operator to combine eliminated 
lines with the remaining lines. This mode 
preserves colored or white pixels at the expense 
of black pixels. 


Sets the bitmap-stretching mode for StretchBlt. The bitmap-stretching mode de- 
fines how information is removed from bitmaps that are compressed by using the 


function. 


The BLACKONWHITE and WHITEONBLACK modes are typically used to 
preserve foreground pixels in monochrome bitmaps. The COLORONCOLOR 
mode is typically used to preserve color in color bitmaps. 


CDC::GetStretchBiltMode, CDC::StretchBlIt, ::SetStretchBltMode 
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CDC::SetTextAlign 

Syntax UINT SetTextAlign( UINT nFlags ); 

Parameters nFlags 


Specifies text-alignment flags. The flags specify the relationship between a 
point and a rectangle that bounds the text. The point can be either the current 
position or coordinates specified by a text-output function. The rectangle that 
bounds the text is defined by the adjacent character cells in the text string. 


The nFlags parameter can be one or more flags from the following three catego- 
ries. Only one flag may be chosen from each category. 


The first category affects text alignment in the x direction: 


Value 


TA_CENTER 


TA_ LEFT 


TA_RIGHT 


Meaning 


Specifies alignment of the point and the horizontal 
center of the bounding rectangle. 


Specifies alignment of the point and the left side of 
the bounding rectangle. This is the default setting. 


Specifies alignment of the point and the right side of 
the bounding rectangle. 


The second category affects text alignment in the y direction: 


Value 


TA_ BASELINE 
TA_BOTTOM 


TA_TOP 


Meaning 


Specifies alignment of the point and the baseline of 
the chosen font. 


Specifies alignment of the point and the bottom of the 
bounding rectangle. 


Specifies alignment of the point and the top of the 
bounding rectangle. This is the default setting. 


The third category determines whether the current position is updated when text 


iS written: 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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Value Meaning 


TA_NOUPDATECP Specifies that the current position is not updated 
after each call to a text-output function. This is 
the default setting. 


TA_UPDATECP Specifies that the current position is updated 
after each call to a text-output function. 


Sets the text-alignment flags. 


The functions TextOut and ExtTextOut use these flags when positioning a string 
of text on a display or device. The flags specify the relationship between a specific 
point and a rectangle that bounds the text. The coordinates of this point are passed 
as parameters to the TextOut member function. The rectangle that bounds the text 
is formed by the adjacent character cells in the text string. 


The previous text-alignment setting. The low-order byte contains the horizontal 
alignment and the high-order byte contains the vertical alignment. The return 


value is 0 if there is an error. 


CDC::ExtTextOut, CDC::GetTextAlign, CDC::TabbedTextOut, 
CDC::TextOut, ::SetTextAlign 


CDC::SetfextCharacterExtra 


int SetTextCharacterExtra( int nCharExtra ); 

nCharExtra 
Specifies the amount of extra space (in logical units) to be added to each charac- 
ter. If the current mapping mode is not MM_ TEXT, nCharExtra is trans- 
formed and rounded to the nearest pixel. 


Sets the amount of intercharacter spacing. GDI adds this spacing to each character, 
including break characters, when it writes a line of text to the device context. 


The amount of the previous intercharacter spacing. 


CDC::GetTextCharacterExtra, ::SetTextCharacterExtra 
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CDC::SetTextColor 


Syntax DWORD SetTextColor( DWORD crColor ); 


Parameters crColor 
Specifies the color of the text as an RGB color value. 


Remarks Sets the text color to the specified color. The system will use this text color when 
writing text to this device context and also when converting bitmaps between 
color and monochrome device contexts. 


If the device cannot represent the specified color, the system sets the text color to 
the nearest physical color. The background color for a character is specified by 
SetBkColor and SetBkMode. 


Return Value An RGB value for the previous text color. 
See Also CDC::GetTextColor, CDC::BitBlt, CDC::SetBkColor, CDC::SetBkMode, 
::SetTextColor 


CDC::SetTextJustification 


Syntax int SetTextJustification( int nBreakExtra, int nBreakCount ); 


Parameters nBreakExtra 
Specifies the total extra space to be added to the line of text (in logical units). If 
the current mapping mode is not MM_ TEXT, the value given by this parame- 
ter is converted to the current mapping mode and rounded to the nearest device 
unit. 


nBreakCount 
Specifies the number of break characters in the line. 


Remarks 


Return Value 


See Also 
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Adds space to the break characters in a string. An application can use 
GetTextMetrics to retrieve a font’s break character. 


After calling the SetText Justification member function, a call to TextOut dis- 
tributes the specified extra space evenly among the specified number of break char- 
acters. The break character is usually the space character (ASCII 32), but may be 
defined by a font as some other character. 


The function GetTextExtent is typically used with SetTextJustification. 
GetTextExtent computes the width of a given line before justification. This width 
is compared to the width of the line after justification to determine how much 
space to add to the line. 


The SetText Justification function can be used to justify a line that contains multi- 
ple runs in different fonts. In this case, the line must be created piecemeal by justi- 
fying and writing each run separately. 


Because rounding errors can occur during justification, the system keeps a running 
error term that defines the current error. When justifying a line that contains multi- 
ple runs, GetTextExtent automatically uses this error term when it computes the 
extent of the next run. This allows the text-output function to blend the error into 
the new run. 


After each line has been justified, this error term must be cleared to prevent it from 
being incorporated into the next line. The term can be cleared by calling 
SetTextJustification with nBreakExtra set to 0. 


One if the function is successful; otherwise 0. 


CDC::GetMapMode, CDC::GetTextExtent, CDC::GetTextMetrics, 
CDC::SetMapMode, CDC::TextOut, ::SetText Justification 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CDC::SetViewportExt 


CSize Set ViewportExt( int x, int y ); 
CSize SetViewportExt( SIZE size ); 


x 
Specifies the x-extent of the viewport (in device units). 


Specifies the y-extent of the viewport (in device units). 
SIZE 
Specifies the x- and y-extents of the viewport (in device units). 


Sets the x- and y-extents of the viewport of the device context. The viewport, 
along with the device-context window, defines how GDI maps points in the 
logical coordinate system to points in the coordinate system of the actual device. 
In other words, they define how GDI converts logical coordinates into device 
coordinates. 


When the following mapping modes are set, calls to SetWindowExt and 
Set ViewportExt are ignored: 


MM_HIENGLISH 
MM_HIMETRIC 
MM_LOENGLISH 
MM_LOMETRIC 
MM_ TEXT 
MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call SetWindowExt 
before it calls Set ViewportExt. 


The previous extents of the viewport as a CSize object. When an error occurs, the 
x- and y-coordinates are both set to 0. 


CDC::SetWindowEXxt, ::SetViewportExt 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CDC::SetViewportOrg 


CPoint SetViewportOrg( int x, int y ); 
CPoint SetViewportOrg( POINT point ); 


x 
Specifies the x-coordinate (in device units) of the origin of the viewport. The 
value must be within the range of the device coordinate system. 


Specifies the y-coordinate (in device units) of the origin of the viewport. The 
value must be within the range of the device coordinate system. 


point 
Specifies the origin of the viewport. The values must be within the range of the 
device coordinate system. You can pass either a POINT structure or a CPoint 
object for this parameter. 


Sets the viewport origin of the device context. The viewport, along with the device- 
context window, defines how GDI maps points in the logical coordinate system to 
points in the coordinate system of the actual device. In other words, they define 
how GDI converts logical coordinates into device coordinates. 


The viewport origin marks the point in the device coordinate system to which GDI 
maps the window origin, a point in the logical coordinate system specified by 
SetWindowOrg. GDI maps all other points by following the same process re- 
quired to map the window origin to the viewport origin. For example, all points in 
a circle around the point at the window origin will be in a circle around the point 
at the viewport origin. Similarly, all points in a line that passes through the win- 
dow origin will be in a line that passes through the viewport origin. 


The previous origin of the viewport (in device coordinates) as a CPoint object. 


CDC::SetWindowOrg, ::SetViewportOrg 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CDC::SetWindowExt 


CSize SetWindowExt( int x, int y ); 


CSize SetWindowExt( SIZE size ); 


x 
Specifies the x-extent (in logical units) of the window. 


Specifies the y-extent (in logical units) of the window. 
size 
Specifies the x- and y-extents (in logical units) of the window. 


Sets the x- and y-extents of the window associated with the device context. The 
window, along with the device-context viewport, defines how GDI maps points in 
the logical coordinate system to points in the device coordinate system. 


When the following mapping modes are set, calls to SetWindowExt and 
Set ViewportExt functions are ignored: 


MM_HIENGLISH 
MM_HIMETRIC 
MM_LOENGLISH 
MM_LOMETRIC 
MM_ TEXT 
MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call the 
SetWindowExt member function before calling Set ViewportExt. 


The previous extents of the window (in logical units) as a CSize object. If an error 
occurs, the x- and y-coordinates of the returned CSize object are both set to 0. 


CDC::Set ViewportExt, ::SetWindowExt, CSize 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CDC::SetWindowOrg 


CPoint SetWindowOrg( int x, int y ); 


CPoint SetWindowOrg( POINT point ); 


x 
Specifies the logical x-coordinate of the new origin of the window. 


Specifies the logical y-coordinate of the new origin of the window. 


point 
Specifies the logical coordinates of the new origin of the window. You can pass 
either a POINT structure or a CPoint object for this parameter. 


Sets the window origin of the specified device context. The window, along with 
the device-context viewport, defines how GDI maps points in the logical coordi- 
nate system to points in the device coordinate system. 


The window origin marks the point in the logical coordinate system from which 
GDI maps the viewport origin, a point in the device coordinate system specified 
by the SetWindowOrg function. GDI maps all other points by following the same 
process required to map the window origin to the viewport origin. For example, all 
points in a circle around the point at the window origin will be in a circle around 
the point at the viewport origin. Similarly, all points in a line that passes through 
the window origin will be in a line that passes through the viewport origin. 


The previous origin of the window as a CPoint object. 


::SetWindowOrg 
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CDC::StartDoc 


Syntax int StartDoc( const char FAR* pDocName ); 


Parameters pDocName 
Pointer to a null-terminated string that specifies the name of the document. The 
document name is displayed in the Print Manager window. The maximum 
length of this string is 31 characters plus the terminating null character. 


Remarks - Informs the device driver that a new print job is starting and that all subsequent 
NEWFRAME escape calls should be spooled under the same job until an 
ENDDOC escape call occurs. This ensures that documents longer than one page 
will not be interspersed with other jobs. 


Return Value The value —1 if there is an error such as insufficient memory or an invalid port 
specification occurs. Otherwise, a positive value. 


See Also CDC::Escape, CDC::EndDoc 


CDC::StartPage 


Syntax int StartPage(); 


Remarks Prepares the printer driver to receive data. 
StartPage supersedes the NEWFRAME and BANDINFO escapes. 


For an overview of the sequence of printing calls, see the StartDoc member 
function. 


See Also CDC::Escape, CDC::EndPage 


Syntax 


Parameters 
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CDC::StretchBit 


BOOL StretchBlt( int x, int y, int nWidth, int nHeight, CDC* pSrcDC, int xSrc, 
int ySrc, int nSrcWidth, int nSrcHeight, DWORD dwkRop ); 


x 
Specifies the x-coordinate (in logical units) of the upper-left corner of the desti- 
nation rectangle. 


Specifies the y-coordinate (in logical units) of the upper-left corner of the desti- 
nation rectangle. 


nWidth 
Specifies the width (in logical units) of the destination rectangle. 


nHeight 
Specifies the height (in logical units) of the destination rectangle. 


pSrcDC 
Specifies the source device context. 


xSrc 
Specifies the x-coordinate (in logical units) of the upper-left corner of the 
source rectangle. 


ySTc 
Specifies the y-coordinate (in logical units) of the upper-left corner of the 
source rectangle. 


nSrc Width 
Specifies the width (in logical units) of the source rectangle. 


nSrcHeight 
Specifies the height (in logical units) of the source rectangle. 


dwRop 
Specifies the raster operation to be performed. Raster operation codes define 
how GDI combines colors in output operations that involve a current brush, a 
possible source bitmap, and a destination bitmap. This parameter may be one of 
the following values: 
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Code 
BLACKNESS 
DSTINVERT 
MERGECOPY 


MERGEPAINT 
NOTSRCCOPY 
NOTSRCERASE 


PATCOPY 
PATINVERT 


PATPAINT 


SRCAND 
SRCCOPY 
SRCERASE 
SRCINVERT 
SRCPAINT 


WHITENESS 


Description 
Turns all output black. 
Inverts the destination bitmap. 


Combines the pattern and the source bitmap using 
the Boolean AND operator. 


Combines the inverted source bitmap with the 
destination bitmap using the Boolean OR operator. 


Copies the inverted source bitmap to the 
destination. 


Inverts the result of combining the destination and 
source bitmaps using the Boolean OR operator. 


Copies the pattern to the destination bitmap. 


Combines the destination bitmap with the pattern 
using the Boolean XOR operator. 


Combines the inverted source bitmap with the 
pattern using the Boolean OR operator. Combines 
the result of this operation with the destination 
bitmap using the Boolean OR operator. 


Combines pixels of the destination and source 
bitmaps using the Boolean AND operator. 


Copies the source bitmap to the destination bitmap. 


Inverts the destination bitmap and combines the 
result with the source bitmap using the Boolean 
AND operator. 


Combines pixels of the destination and source 
bitmaps using the Boolean XOR operator. 


Combines pixels of the destination and source 
bitmaps using the Boolean OR operator. 


Turns all output white. 


Remarks 


Return Value 


See Also 
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Moves a bitmap from a source rectangle into a destination rectangle, stretching or 
compressing the bitmap if necessary to fit the dimensions of the destination rec- 
tangle. The function uses the stretching mode of the destination device context (set 
by SetStretchBltMode) to determine how to stretch or compress the bitmap. 


The StretchBlt function moves the bitmap from the source device given by 
pSrcDC to the destination device represented by the device-context object whose 
member function is being called. The xSrc, ySrc, nSrcWidth, and nSrcHeight 
parameters define the upper left corner and dimensions of the source rectangle. 
The x, y, nWidth, and nHeight parameters give the upper-left corner and dimen- 
sions of the destination rectangle. The raster operation specified by dwRop defines 
how the source bitmap and the bits already on the destination device are combined. 


The StretchBlt function creates a mirror image of a bitmap if the signs of the 
nSrcWidth and nWidth or nSrcHeight and nHeight parameters differ. If nSrcWidth 
and nWidth have different signs, the function creates a mirror image of the bitmap 
along the x-axis. If nSrcHeight and nHeight have different signs, the function 
creates a mirror image of the bitmap along the y-axis. 


The StretchBIt function stretches or compresses the source bitmap in memory, 
then copies the result to the destination. If a pattern is to be merged with the result, 
it is not merged until the stretched source bitmap is copied to the destination. If a 
brush is used, it is the selected brush in the destination device context. The destina- 
tion coordinates are transformed according to the destination device context; the 
source coordinates are transformed according to the source device context. 


If destination, source, and pattern bitmaps do not have the same color format, 
StretchBlt converts the source and pattern bitmaps to match the destination bit- 
maps. The foreground and background colors of the destination are used in the 
conversion. 


If StretchBlt must convert a monochrome bitmap to color, it sets white bits (1) to 
background color and black bits (0) to foreground color. To convert color to mono- 
chrome, it sets pixels that match the background color to white (1), and sets all 
other pixels to black (0). The foreground and background colors of the device con- 
text with color are used. Not all devices support the function. 


For more information, see the RC_BITBLT capability in GetDeviceCaps mem- 
ber function. 


TRUE if the bitmap is drawn; otherwise FALSE. 


CDC: :BitBIt, CDC::GetDeviceCaps, CDC::SetStretchBltMode, ::StretchBlt 
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Syntax 


Parameters 


Remarks 


CDC::TabbedTextOut 


CSize Tabbed TextOut( int x, int y, const char FAR®* [pString, int nCount, 
int nTabPositions, LPINT [pnTabStopPositions, int nTabOrigin ); 


x 
Specifies the logical x-coordinate of the starting point of the string. 


Specifies the logical y-coordinate of the starting point of the string. 


lpString 
Points to the character string to draw. You can pass either a const FAR pointer 
to an array of characters or a CString object for this parameter. 


nCount 
Specifies the number of characters in the string. 


nTabPositions 
Specifies the number of values in the array of tab-stop positions. 


[pnTabStopPositions 
Points to an array containing the tab-stop positions (in device units). The tab 
stops must be sorted in increasing order; the smallest x-value should be the first 
item in the array. 


nTabOrigin 
Specifies the x-coordinate of the starting position from which tabs are expanded 
(in logical units). 


Writes a character string at a specified location, expanding tabs to the values 
specified in an array of tab-stop positions. Text is written in the currently selected 
font. If nTabPositions is 0 and [pnTabStopPositions is NULL, tabs are expanded 
to eight times the average character width. 


If nTabPositions is 1, the tab stops are separated by the distance specified by the 
first value in the /pnTabStopPositions array. 


Return Value 


See Also 


Syntax 


Parameters 
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If the IpnTabStopPositions array contains more than one value, a tab stop is set for 
each value in the array, up to the number specified by nTabPositions. 


The nTabOrigin parameter allows an application to call the TabbedTextOut func- 
tion several] times for a single line. If the application calls the function more than 
once with the nTabOrigin set to the same value each time, the function expands all 
tabs relative to the position specified by nTabOrigin. 


By default, the current position is not used or updated by the function. If an apphi- 
cation needs to update the current position when it calls the function, the applica- 
tion can call SetTextAlign with nFlags set to TA. UPDATECP. When this flag 
is set, Windows ignores x and y on subsequent calls to TabbedTextOut, using the 
current position instead. 


The dimensions of the string (in logical units) as a CSize. 


CDC::GetTabbedTextExtent, CDC::SetTextAlign, CDC::TextOut, 
:: TabbedTextOut 


CDC::TextOut 


BOOL TextOut( int x, int y, const char FAR* /pString, int nCount ); 


BOOL TextOut( int x, int y, const CString& str ); 


x 
Specifies the logical x-coordinate of the starting point of the text. 


Specifies the logical y-coordinate of the starting point of the text. 
lpString 
The pointer to the characters to write. 


nCount 
Specifies the number of characters to write. 


Str 
A CString object or null-terminated string that contains the chararacters to 
write. 
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Remarks 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


Writes a character string at a specified location, using the currently selected font. 


Character origins are at the upper-left corner of the character cell. By default, the 
current position is not used or updated by the function. 


If an application needs to update the current position when it calls TextOut, the ap- 
plication can call SetTextAlign with nFlags set to TA_UPDATECP. When this 
flag is set, Windows ignores x and y on subsequent calls to TextOut, using the cur- 
rent position instead. 


TRUE if the function is successful; otherwise FALSE. 


CDC::ExtTextOut, CDC::GetTextExtent, CDC::SetTextAlign, 
CDC::SetTextColor, CDC::TabbedTextOut, ::TextOut 


CDC::UpdateColors 


void UpdateColors(); 


Updates the client area of the device context by matching the current colors in the 
client area to the system palette on a pixel-by-pixel basis. An inactive window 
with a realized logical palette may call UpdateColors as an alternative to redraw- 
ing its client area when the system palette changes. 


For more information on using color palettes, see the Windows Software Develop- 
ment Kit documentation. 


The UpdateColors member function typically updates a client area faster than re- 
drawing the area. However, because the function performs the color translation 
based on the color of each pixel before the system palette changed, each call to 
this function results in the loss of some color accuracy. 


CDC::RealizePalette, CPalette, :: UpdateColors 
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Class CDialog : public CWnd 


The CDialog class is an abstract class for displaying 
dialog boxes on the screen. To get a modeless dialog 
box, you must derive your own class from CDialog. 
To derive modal dialog boxes, use the CModalDialog 
class. The constructors for class CDialog are pro- 
tected, so you must derive your own class. 
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A modeless dialog box allows the user to display the dialog box and return to 
another task without canceling or removing the dialog box. A modal dialog box re- 
quires the user to close the dialog box before the application continues. 


You can create a modeless dialog in one step or two. To create it in one step, write 
the constructor so it calls the object’s Create member function. To create it in two 
steps, don’t include a call to Create in the constructor. Invoke the constructor for 
your dialog object, then call the object’s Create member function. 


A modeless dialog box receives messages from Windows like any other window. 
To process messages in your derived dialog-box class, provide message-handler 
member functions for the messages the dialog box can process. 


Your message-handler member functions specify what happens when the user 
works with your dialog box. Typically, you’ Il override the OnInitDialog member 
function when you need to initialize controls (such as setting the initial text of an 
edit box). 


You'll also override the OnClose member function of your derived dialog class to 
call CWnd::Destroy Window. Instead of calling DestroyWindow, you can call 
the C++ delete operator on the this reference, which calls Destroy Window for 
you. 


Your derived dialog-box class can also add member variables to store data entered 
by the user or data for display to the user. You can add member functions to set or 
get these values. A modeless dialog box can also send messages to its parent 
window. 


Create your dialog box from a dialog-box resource template, as in traditional 
Windows. The dialog-box resource specifies a template name or ID, a font to use, 
a set of controls, such as buttons and edit boxes, and the window styles that apply 
to the dialog box. To create a dialog box from a template, specify the template in 
your .RC file and compile it with a resource compiler. The resulting .RES file is 
sent to the linker, which incorporates the resource information with your execut- 
able program. Specify the name or ID of the template when you call the Create 
member function from your dialog-box constructor. 
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See Also 


Public Members 


CDialog 


Instead of creating your dialog box from a compiled resource, you can build the 
resource yourself in memory, construct an object of your class derived from 
CDialog, and use the CreateIndirect member function to create the dialog box 
from the template in memory. The template constructed in memory uses a 
DLGTEMPLATE data structure, as described in the Windows Software 
Development Kit documentation. 


If the dialog-box template (in a resource file or in memory) specifies the 

WS_ VISIBLE style, the dialog-box window appears in its parent window. Other- 
wise, you must call the ShowWindow member function, which CDialog inherits 
from class CWnd. 


After the call to Create, Windows sends a WM_INITDIALOG message to the 
dialog box. You can override the OnInitDialog member function to perform 
dialog-box initialization chores. For example, if your dialog box displays statistics 
about the current font, you can override OnInitDialog to set the current values of 
the static text controls in the dialog box to reflect the statistics. 


Although the dialog-box template can specify the dialog-box font, you can also 
set the font on the fly. If the dialog-box template specifies the DS_SETFONT 
style, Windows sends a WM_SETFONT message to the dialog box before creat- 
ing the controls. In response to this message, the application calls the OnSetFont 
member function. You can override that message-handler function to set the 
dialog-box font. 


When the user terminates a modeless dialog box, call the DestroyWindow mem- 
ber function, which CDialog inherits from class CWnd, to remove the dialog win- 
dow and destroy its data structures. You can call Destroy Window from the 
OnOK, OnCancel, or OnClose member functions, which you can override from 
class CWnd. If you allocate any memory in the dialog object, override the 
CDialog destructor to dispose of the allocations. 


CModalDialog 

Operations 

MapDialogRect Converts the dialog-box units of a rectangle to 
screen units. 

IsDialogMessage Determines whether the given message is intended 
for the modeless dialog box and, if so, processes it. 

NextDigCtrl | Moves the focus to the next dialog-box control in 


the dialog box. 


PrevDigCtrl 
GotoDigCtrl 
SetDefID 
GetDefID 


EndDialog 


Overridables 
OnInitDialog 
OnSetFont 


Protected Members 


Construction/Destruction 
CDialog 


Initialization 
Create 


CreateIndirect 
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Moves the focus to the previous dialog-box control 
in the dialog box. 


Moves the focus to a specified dialog-box control 
in the dialog box. 


Changes the default push button control for a 
dialog box to a specified push button. 


Gets the ID of the default push button control for a 
dialog box. 


Terminates a modal dialog box. 


Override to augment dialog-box initialization. 


Override to specify the font that a dialog-box con- 
trol is to use when drawing text. 


Constructs a CDialog object. 


Initializes the CDialog object. Creates the mode- 
less dialog and attaches it to the CDialog object. 


Creates a modeless dialog box from a dialog-box 
template in memory. 
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Member Functions 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CDialog::CDialog 
CDialog(); 


The CDialog constructor is protected because you must derive your own dialog- 
box class to implement a dialog. 


Construction of a modeless dialog is a two-step process. First invoke the construc- 
tor, then call either form of the Create member function. You can combine the 
steps by calling Create from within your constructor. 


CDialog::Create, CDialog::CreateIndirect 


CDialog::Create 


BOOL Create( const char FAR* [pTemplateName, 
CWnd* pParentWnd=NULL); / 


BOOL Create( UINT nl/DTemplate, CWna* pParentWnd =NULL ); 


lpTemplateName — 
Contains a null-terminated string that is the name of a dialog-box resource 
template. 


pParentWnd 
Points to the parent window object (of type CWnd) to which the dialog object 
belongs. If itis NULL, the dialog object’s parent window is set to the main ap- 
plication window, as shown in the following code: 


if( pParentWnd == NULL ) 
pParentWnd = AfxGetApp()->m_pMainWnd; 


nIDTemplate 
Contains the ID number of a dialog-box resource template. 


Call Create when you construct your dialog-box object. You can put the call to 
create inside the constructor or call it after the constructor executes. 


Return Value 


See Also 
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Two forms of the Create member function are provided for access to the dialog 
template resource either by template name or by template ID number. 


For either form, you also pass a pointer to the parent window object. If you don’t, 
the dialog will be created with its parent window set to the main application win- 
dow. Modeless dialogs can use this pointer to send messages to the parent if 
needed. 


Before the dialog box is displayed, Windows sends the WM_INITDIALOG mes- 
sage to the dialog box. If the dialog box has the DS_SETFONT style, Windows 
also sends the WM_SETFONT message before the control windows are created. 
You can override the OnInitDialog and OnSetFont member functions to provide 
special handling of these messages. 


The Create member function returns immediately after it creates the dialog box. 


Use the WS_ VISIBLE style in the dialog template if the dialog box should ap- 
pear when the parent window is created. You can also specify other dialog styles 
in the template as explained in the Windows Software Development Kit documen- 
tation. These include styles that specify: 


= The frame around the dialog box. 

= Whether the dialog window is a pop-up or child window. 

= Whether the dialog box has a border or a Control menu. 

= How controls are to be grouped and the tabbing order between them. 


Use the CWnd:: Destroy Window function to destroy a dialog box created by the 
Create function. 


A dialog box can contain up to 255 controls. 


Both forms return TRUE if dialog creation and initialization was successful: other- 
wise FALSE. 


CWnd::Destroy Window, CDialog::CreateIndirect, ::CreateDialog, 
WM_SETFONT, WM_INITDIALOG 
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Syntax 


Parameters 


Remarks 


CDialog::Createlndirect 


Protected: 
BOOL CreatelIndirect( const BYTE FAR®* [pDialogTemplate, 
CWnd* pParentWnd = NULL); 


[pDialogTemplate 
Points to a global memory object that contains a dialog-box template used to 
create the dialog box. An application must build the dialog-box template accord- 
ing to the guidelines outlined in the description of the application-defined 
DLGTEMPLATE data structure. 


pParentWnd 
Points to the dialog object’s parent window object (of type CWnd). If it is 


NULL, the dialog object’s parent window is set to the main application win- 
dow, as shown in the following code: 


if( pParentWnd == NULL ) 
pParentWnd = AfxGetApp()->m_pMainWnd; 


Creates a modeless dialog box from a dialog-box template in memory. 
CreateIndirect is protected. 


Before the dialog box is displayed, Windows sends the WM_INITDIALOG mes- 
sage to the dialog box. If the dialog box has the DS_SETFONT style, Windows 
also sends the WM_SETFONT message before the control windows are created. 
You can override the OnInitDialog and OnSetFont member functions to provide 
special handling of these messages. 


The CreateIndirect member function returns immediately after 1t creates the 
dialog box. 


Use the WS_ VISIBLE style in the dialog-box template if the dialog box should 
appear in the parent window upon creation. You can also specify other dialog 
styles in the template as explained in the Windows Software Development Kit 
documentation. These include styles that specify: 


= The frame around the dialog box. 
=» Whether the dialog window 1s a pop-up or child window. 
= Whether the dialog box has a border or a Control menu. 


= How controls are to be grouped and the tabbing order between them. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


See Also 
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Use the CWnd::Destroy Window function to destroy a dialog box created by the 
CreateIndirect function. 


A dialog box can contain up to 255 controls. 
TRUE if the dialog was created and initialized successfully; otherwise FALSE. 


CDialog::Create, CWnd::DestroyWindow, WM_INITDIALOG, 
WM_SETFONT 


CDialog::EndDialog 
void EndDialog( int nResult ); 


nResult 


Contains the value to be returned from the dialog box to the member function 
that created it. 


Used for modal dialog boxes. Modeless dialogs do not use this member function. 


The EndDialog member function terminates a modal dialog box and returns the 
given result to the function that created the dialog box. The EndDialog function is 
required to complete processing whenever a modal dialog box is created and may 
not be used for any other purpose. 


The dialog function can call EndDialog at any time, even during the processing of 
the WM_INITDIALOG message in OnInitDialog. If called during processing of 
the WM_INITDIALOG message, the dialog box is terminated before it is shown 
or before the input focus is set. 


EndDialog does not close the dialog box immediately. Instead, it sets a flag that 
directs the dialog box to close as soon as the standard Foundation dialog-box func- 
tion (AfxDlgProc) ends. The EndDialog function returns to the dialog-box func- 
tion, so it must return control to Windows. 


CModalDialog, CDialog::Create, CDialog::CreateIndirect, 
WM_INITDIALOG 
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Syntax 


Remarks 


Return Value 


See Also 


syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


CDialog::GetDeflD 


DWORD GetDefIDQ; 


Call the GetDefID member function to get the ID of the default push button con- 
trol for a dialog box. This is usually an OK button. 


A 32-bit value (DWORD). If the default push button has an ID value, the high- 
order word contains DC_HASDEFID and the low-order word contains the ID 


value. If the default push button does not have an ID value, the return value is 0. 


CDialog::SetDefID 


CDialog::GotoDIigCtri 


void GotoDlgCtrl( CWnd* pWndCtrl ); 


pWndCtrl 
Identifies the window (control) that is to receive the focus. 


Moves the focus to the specified control in the dialog. 


To get a pointer to the control (child window) to pass as pWndCtrl, call the 
GetDlgItem member function, which returns the pointer as a pointer to a CWnd 
object. This pointer can then be cast to its specific type. GetDlgItem is inherited 
from class CWnd. 


CWnd::GetDigItem, CDialog::PrevDigCtrl, CDialog::NextDlgCtrl 


CDialog::lsDialogMessage 
BOOL IsDialogMessage( LPMSG /pMsg ); 


lpMsg 
Points to an MSG structure that contains the message to be checked. 
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The MSG structure looks like this: 


typedef struct tagMSG { 
HWND hwnd; 
WORD message; 
WORD wParam; 
LONG 1Param; 


DWORD time; 
POINT pt; 
} MSG; 
Remarks Determines whether the given message is intended for the modeless dialog box 


and automatically processes the message if it is. When the IsDialogMessage func- 
tion processes a message, it checks for keyboard messages and converts them to 
selection commands for the corresponding dialog box. For example, the TAB key 
selects the next control or group of controls, and the DOWN ARROW key selects the 
next control in a group. 


A message processed by IsDialogMessage must not be passed to the 
TranslateMessage or DispatchMessage Windows functions. The message has al- 
ready been processed. 


IsDialogMessage sends the WM_GETDLGCODE message to determine which 
keys to process. 


Return Value Specifies whether the given message has been processed. It is TRUE if the mes- 
sage has been processed; otherwise FALSE. If the return is FALSE, call the 
PreTranslateMessage member function of the base class to process the message. 
The code looks like this in an override of the CDialog PreTranslateMessage 
member function: 


CMyDlg::PreTranslateMessage( msg ) 


{ 
if( IsDialogMessage( msg ) 
return TRUE; 
else 
return CDialog::PrelTranslateMessage( msg ); 
} 
See Also ::DispatchMessage, ::TranslateMessage, ::GetMessage, 


CWnd::PreTranslateMessage, WM_GETDLGCODE 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


CDialog::MapDialogRect 
void MapDialogRect( LPRECT [pRect ) const; 


lpRect 
Points to a RECT structure that contains the dialog-box coordinates to be 
converted. 


Converts the dialog-box units of a rectangle to screen units. Dialog-box units are 
stated in terms of the current dialog base unit derived from the average width and 
height of characters in the font used for dialog-box text. 


Typically, dialog boxes use the system font, but a different font may be specified 
by using the DS_SETFONT style in the resource-definition file. One horizontal 
unit is one-fourth of the dialog-box base width unit, and one vertical unit is one- 
eighth of the dialog-box base height unit. The Windows function 
GetDialogBaseUnits returns the dialog-box base units in pixels. 


The MapDialogRect member function replaces the dialog-box units in /pRect 
with screen units (pixels), so that the rectangle can be used to create a dialog box 
or position a control within a box. 


::GetDialogBaseUnits, CDialog::Create, CDialog::CreateIndirect, 
WM_SETFONT 


CDialog::NextDigCtri 


void NextDlgCtrlQ) const; 


Moves the focus to the next control in the dialog box. If the focus is at the last con- 
trol in the dialog box, it moves to the first control. 


CDialog::PrevDigCtrl, CDialog::GotoDlgCtrl 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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CDialog::OninitDialog 
virtual BOOL OnInitDialog(); 


Called in response to the WM_INITDIALOG message. This message is sent 
during the Create or CreateIndirect call, which occurs immediately before the 
dialog box is displayed. Override it if you need to perform special processing 
when the dialog box is initialized. 


The OnInitDialog function is called via the standard global dialog-box procedure, 
AfxDlgProc, common to all Microsoft Foundation Class Library dialogs, rather 
than through your message map, so you do not need a message-map entry for this 
member function. 


Returns TRUE by default, indicating successful dialog initialization. 


CDialog::Create, CDialog::CreateIndirect, WM_INITDIALOG 


CDialog::OnSetFont 


virtual void OnSetFont( CFont* pFont ); 


pFont 
Specifies a pointer to the font. If this parameter is NULL, the control will draw 
text using the default system font. 


Specifies which font a dialog-box control is to use when drawing text. 


The dialog-box font normally gets set in the .RC resource file as part of the dialog- 
box resource template. If you want to set it instead at run time, specify the 
DS_SETFONT style in your dialog-box template. With that style set, Windows 
sends a WM_SETFONT message to the dialog box before creating the controls. 
The OnSetFont member function is then called automatically via the standard 
dialog-box procedure. 
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See Also 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


The application should call the CGdiObject::DeleteObject function to delete the 
font when it is no longer needed, such as after the control is destroyed. Also call 
CGdiObject::DeleteObject to delete the old font before you set the new one. 

The size of the control is not changed as a result of receiving this message. To pre- 
vent Windows from clipping text that does not fit within the boundaries of the con- 
trol, the application should correct the size of the control window before changing 
the font. 


For more information about dialog resource templates, see the Windows Software 
Development Kit documentation. 


WM_SETFONT 


CDialog::PrevDigCtri 


void PrevDigCtrlQ) const; 


Sets the focus to the previous control in the dialog box. If the focus is at the first 
control in the dialog box, it moves to the last control in the dialog box. 


CDialog::NextDlgCtrl, CDialog::GotoDlgCtrl 


CDialog::SetDefiD 


void SetDefID( UINT n/JD ); 


nID 
Specifies the ID of the push button control that will become the default. 


Changes the default push button control for a dialog box. 


CDialog::GetDefID 
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class CDumpContext 


Preconditions 


Comments 


See Also 


The CDumpContext class supports stream-oriented diagnostic output in the form 
of human-readable text. You can use afxDump, a predeclared CDumpContext 
object, for most of your dumping. The afxDump object is available only in the 
Debug version of the Microsoft Foundation Class Library. 


Several of the memory diagnostic functions use afxDump for their output. 


Before you create your own CDumpContext object, you must create a CFile ob- 
ject that serves as the dump destination. 


The predefined afxDump object, conceptually similar to the cerr stream, is con- 
nected to stderr under MS-DOS. Under the Windows environment, the output is 
routed to the debugger via the Windows function OutputDebugString. 


The CDumpContext class has an overloaded insertion (<<) operator for CObject 
pointers that dumps the object’s data in hexadecimal form. If you need a custom 
dump format for a derived object, override CObject::Dump. Most Microsoft 
Foundation classes have a Dump member function defined. 


Classes that are not derived from CObject, such as CString, CTime, and 
CTimeSpan, have their own overloaded CDumpContext insertion operators, as 
do often-used structures such as CFileStatus, CPoint, and CRect. 


_If you use the IMPLEMENT_DYNAMIC or IMPLEMENT_SERIAL macros 


in the implementation of your class, then CObject::Dump will print the name of 
your CObject-derived class. Otherwise, it will print CObject. 


The CDumpContext class is available with both the Debug and Release versions 
of the library, but the class Dump functions are defined only in the Debug version. 
Use #ifdef _DEBUG / #endif statements to bracket your diagnostic code, includ- 
ing your custom Dump member functions. 


#define DEBUG 


#include <afx.h> 


CFile, CObject 
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Public Members 


Construction/Destruction 
CDumpContext 


Basic 1/0 
Flush 
operator << 


HexDump 


Status 
GetDepth 


SetDepth 


Constructs a CDumpContext object. 


Flushes any data in the dump context buffer. 
Inserts variables and objects into the dump context. 


Dumps bytes in hexadecimal format. 


Gets an integer corresponding to the depth of 
the dump. 


Sets the depth of the dump. 
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Member Functions 


CDumpContext::CDumpContext 


syntax CDumpContext( CFile* pFile ) 
throw( CMemoryException, CFileException ); 


Parameters pFile 
A pointer to the CFile object that is the dump destination. 


Remarks Constructs an object of class CDumpContext. 


The afxDump object is constructed automatically. The output from afxDump is 
sent to stderr. 


Do not write to the underlying CFile while the dump context is active; otherwise 
you will interfere with the dump. 


Example extern char* pFileName; 
CFile f; 


if( !f.Open( pFileName, CFile::modeCreate | CFile::modeWrite ) ) { 
afxDump << "Unable to open file” << "\\n"; 
exit( 1 ); : 

} 

CDumpContext dc( &f ); 


CDumpContext::Flush 


Syntax void Flush() 
throw( CFileException ); 


Remarks Forces any data remaining in buffers to be written to the file attached to the dump 
context. 


Example afxDump.Flush(); 
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CDumpContext::GetDepth 


Syntax int GetDepth() const; 

Remarks Determines if a deep or shallow dump is in process. 
Return Value The depth of the dump as set by SetDepth. 
Example See the example for SetDepth. 

See Also SetDepth 


CDumpContext::HexDump 


Syntax void HexDump( const char* pszLine, BYTE* pby, int nBytes, int nWidth ) 
throw( CFileException ); 


Parameters pszLine 
A string to output at the start of a new line. 


pby 
A pointer to a buffer containing the bytes to dump. 


nBytes 
The number of bytes to dump. 


nWidth 
Maximum number of bytes dumped per line (not the width of the output line). 


Remarks Dumps an array of bytes formatted as hexadecimal numbers. 


Example char test{] = "This is a test of CDumpContext: :HexDump\\n"; 
afxDump.HexDump( ".", (BYTE*) test, sizeof test, 20 ); 


The output from this program is: 


. 54 68 69 73 20 69 73 20 61 20 74 65 73 74 20 6F 66 20 43 44 
. 75 6D 70 43 6F 6E 74 65 78 74 3A 3A 48 65 78 44 75 6D 7@ BA 
. 00 


Syntax 


Parameters 


Remarks 


Example 


See Also 
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CDumpContext::SetDepth 


void SetDepth( int nNewDepth ); 


nNewDepth 
The new depth value. 


Sets the depth for the dump. If you are dumping primitive types or simple 
CObjects that contain no pointers to other objects, then a value of 0 is sufficient. 
A value greater than 0 specifies a deep dump where all objects are dumped recur- 
sively. For example, a deep dump of a collection will dump all elements of the col- 
lection. You may use other specific depth values in your derived classes. 


Note Circular references are not detected in deep dumps and can result in infinite 
loops. 


afxDump.SetDepth( 1 ); // specifies deep dump 
ASSERT( afxDump.GetDepth() == 1 ); 


CObject::Dump 
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Operators 


CDumpContext::operator << 


Syntax CDumpContext& operator <<( const CObject* pOb ) 
throw( CFileException ); 


CDumpContext& operator <<( const CObject& ob ) 
throw( CFileException ); 


CDumpContext& operator <<( const char FAR* [psz ) 
throw( CFileException ); 


CDumpContext& operator <<( const void FAR* /p ) 
throw( CFileException ); 


CDumpContext& operator <<( const void NEAR* np ) 
throw( CFileException ); 


CDumpContext& operator <<( BYTE by ) 
throw( CFileException ); 


CDumpContext& operator <<( WORD w ) 
throw( CFileException ); | 


CDumpContext& operator <<( DWORD dw ) 
throw( CFileException ); 


CDumpContext& operator <<( int 7 ) 
throw( CFileException ); 


CDumpContext& operator <<( LONG /7 ) 
throw( CFileException ); 


CDumpContext& operator <<( UINT 7 ) 
throw( CFileException ); 


Remarks Outputs the specified data to the dump context. 


The insertion operator is overloaded for CObject pointers as well as for most 
primitive types. A pointer to char results in a dump of string contents; a pointer to 
void results in a hexadecimal dump of the address only. 


If you use the IMPLEMENT_DYNAMIC or IMPLEMENT_SERIALE macros 
in the implementation of your class, then the insertion operator, through 
CObject::Dump, will print the name of your CObject-derived class. Otherwise, 


Return Value 


Example 
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it will print CObject. If you override the Dump function of the class, then you can 
provide a more meaningful output of the object’s contents instead of a hexadeci- 
mal dump. 


A CDumpContext reference that enables multiple insertions on a single line. 


extern CObList 1i; 
CString s = “test"; 
Int t= 7 

long 10 = 1000000000L; 


afxDump << "list=" << &li << “string=" 
RG Si MIMS COT Re onga" Re hoa Se AAs 
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class CDWordArray : public CObject 


Public Members 


The CDWordArray class supports arrays of 32-bit 
double words. 


The member functions of CDWordArray are similar 
to the member functions of class CObArray. Be- 
cause of this similarity, you can use the CObArray reference documentation for 
member function specifics. Wherever you see a CObject pointer as a function 
parameter or return value, substitute a DWORD. 


CObject* CObArray::GetAt( int <nIndex> ) const; 


for example, translates to 


DWORD CWordArray::GetAt( int <nIndex> ) const; 


CDWordArray incorporates the IMPLEMENT_SERIAL macro to support seri- 
alization and dumping of its elements. If an array of double words is stored to an 
archive, either with the overloaded insertion operator or with the Serialize mem- 
ber function, each element is, in turn, serialized. 


If you need debug output from individual elements in the array, you must set the 
depth of the CDumpContext object to 1 or greater. 


#include <afxcoll.h> 


Construction/Destruction 


CDWordArray Constructs an empty array for double words. 
~CDWordArray Destroys a CDWordArray object. 

Bounds 

GetSize Gets the number of elements in this array. 
GetUpperBound Returns the largest valid index. 

SetSize Sets the number of elements to be contained in this 


array. 


Operations 
FreeExtra 


RemoveAll 


Element Access 
GetAt 
SetAt 


ElementAt 


Growing the Array 
SetAtGrow 


Add 


Insertion/Removal 
InsertAt 


RemoveAt 


Operators 
operator [ | 
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Frees all unused memory above the current upper 
bound. 


Removes all the elements from this array. 


Returns the value at a given index. 


Sets the value for a given index; array not allowed 
to grow. 


Returns a temporary reference to the double word 
within the array. 


Sets the value for a given index, growing the array 
if necessary. 


Adds an element to the end of the array. 


Inserts an element at a specified index. 


Removes an element at a specific index. 


Sets or gets the element at the specified index. 
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CEdit 


class CEdit : public CWnd 


See Also 


The CEdit class provides the functionality of a 
Windows edit control. An edit control 1s a rectangular 
child window in which the user can enter text. 


You create an edit control in two steps. First, call the 
constructor CEdit to construct the CEdit object, then 
call the Create member function to create the 
Windows edit control and attach it to the CEdit object. 


Construction can be a one-step process in a class derived from CEdit. Write a con- 
structor for the derived class and call Create from within the constructor. 


If you want to handle the Windows notification messages sent by a CEdit object 
to its parent (usually a class derived from CDialog), add the following message- 
map entries and message-handler member functions to the parent class: 


ON_ COMMAND 
ON_EN_SETFOCUS 
ON_EN_KILLFOCUS 
ON_EN_ MAXTEXT 
ON_EN_ CHANGE 
ON_EN_UPDATE 
ON_EN_HSCROLL 
ON_EN_ VSCROLL 


If you create a CEdit object within a dialog box, the CEdit is automatically de- 
stroyed when the user closes the dialog box. 


If you create a CEdit object within a window, you may also need to destroy it. If 
you create the CEdit object on the stack, it is destroyed automatically. If you cre- 
ate the CEdit object on the heap by using the new function, you must call delete 
on the object to destroy it when the user terminates the Windows edit control. If 
you allocate any memory in the CEdit object, override the CEdit destructor to dis- 
pose of the allocations. 


CWnd, CButton, CComboBox, CListBox, CScrollBar, CStatic, 
CModalDialog, CDialog 


Public Members 


Construction/Destruction 
CEdit 


Initialization 
Create 


Multiple-Line Operations 
GetLineCount 


GetHandle 
SetHandle 
FmtLines 
LineIndex 
SetRect 
SetRectNP 


SetTabStops 


General Operations 
CanUndo 


GetModify 
SetModify 


GetRect 
GetSel 
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Constructs a CEdit control object. 


Creates the Windows edit control and attaches it to 
the CEdit object. 


Retrieves the number of lines in a multiple-line 
edit control. 


Retrieves a handle to the memory currently allo- 
cated for a multiple-line edit control. 


Sets the handle to the local memory that will be 
used by a multiple-line edit control. 


Sets the inclusion of soft line-break characters on 
or off within a multiple-line edit control. 


Retrieves the character index of a line within a 
multiple-line edit control. 


Sets the formatting rectangle of a multiple-line edit 
control and updates the control. 


Sets the formatting rectangle of a multiple-line edit 
control without updating the control. 


Sets the tab stops in a multiple-line edit control. 


Determines if an edit-control operation can be 
undone. 


Determines if the contents of an edit control have 
been modified. 


Sets or clears the modification flag for an edit 
control. 


Gets the formatting rectangle of an edit control. 


Gets the starting and ending character positions of 
the current selection in an edit control. 
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CEdit 


GetLine 


EmptyUndoBuffer 


LimitText 
LineFromChar 


LineLength 
LineScroll 


ReplaceSel 
SetPasswordChar 


SetSel 
Undo 


Clear 


Copy 


Cut 


Paste 


Retrieves a line of text from an edit control. 
Resets (clears) the undo flag of an edit control. 


Limits the length of the text that the user may enter 
into an edit control. 


Retrieves the line number of the line that contains 
the specified character index. 


Retrieves the length of a line in an edit control. 
Scrolls the text of a multiple-line edit control. 


Replaces the current selection in an edit control 
with the specified text. 


Sets or removes a password character displayed in 
an edit control when the user enters text. 


Selects a range of characters in an edit control. 
Reverses the last edit-control operation. 


Deletes (clears) the current selection (if any) in the 
edit control. 


Copies the current selection (if any) in the edit con- 
trol to the Clipboard in CF_ TEXT format. 


Deletes (cuts) the current selection (if any) in the 
edit control, and copies the deleted text to the 
Clipboard in CF_TEXT format. 


Inserts the data from the Clipboard into the edit 
control at the current cursor position. Data is in- 
serted only if the Clipboard contains data in 
CF_TEXT format. 
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Member Functions 
CEdit::CanUndo 
Syntax BOOL CanUndo() const; 
Return Value TRUE if the last edit operation can be undone by a call to the Undo member func- 


tion; FALSE if it cannot be undone. 


See Also CEdit:: Undo, EM_CANUNDO 


CEdit::CEdit 


Syntax CEdit(); 
Remarks Constructs a CEdit object. 
See Also CEdit::Create 


CEdit::Clear 


Syntax void Clear(); 


Remarks Deletes (clears) the current selection (if any) in the edit control. 


The deletion performed by Clear can be undone by calling the Undo member 
function. 


To delete the current selection and place the deleted contents into the Clipboard, 
call the Cut member function. 


See Also CEdit::CanUndo, CEdit::Undo, CEdit::Copy, CEdit::Cut, CEdit::Paste, 
WM_CLEAR 
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Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CEdit::Copy 


void CopyQ; 


Copies the current selection (if any) in the edit control to the Clipboard in 
CF_TEXT format. 


CEdit::Clear, CEdit::Cut, CEdit::Paste, WM_COPY 


CEdit::Create 


BOOL Create( DWORD dwStyle, const RECT & rect, CWnd* pParentWnd, 
UINT nID ); 


dwStyle 
Specifies the edit control’s style. 


rect 
Specifies the edit control’s size and position. 


pParentWnd 
Specifies the edit control’s parent window (usually a CDialog or 
CModalDialog). It must not be NULL. 


nlID 
Specifies the edit control’s ID. 


You construct a CEdit object in two steps. First, call the CEdit constructor, then 
call Create, which creates the Windows edit control and attaches it to the CEdit 
object. 


When Create executes, Windows sends the WM_NCCREATE, 
WM_NCCALCSIZE, WM_ CREATE, and WM_GETMINMAXINFO 
messages to the edit control. 


These messages are handled by default by the OnNcCreate, OnNcCalcSize, 
OnCreate, and OnGetMinMaxInfo member functions in the CWnd base class. 
To extend the default message handling, derive a class from CEdit, add a message 
map to the new class, and override the above message-handler member functions. 
Override OnCreate, for example, to perform needed initialization for the new 
class. 
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To handle Windows notification messages sent from a CEdit object to its parent, 
add the following message-map entries to the parent class message map: 


ON_COMMAND 
ON_EN_SETFOCUS 
ON_EN_KILLFOCUS 
ON_EN_ MAXTEXT 
ON_EN_ CHANGE 
ON_EN_UPDATE 
ON_EN_HSCROLL 
ON_EN_VSCROLL 


Apply the following window styles to an edit control: 


Style Application 

WS_ CHILD Always. 

WS_ VISIBLE Usually. 

WS_DIABLED Rarely. 

WS_GROUP To group controls. 

WS_TABSTOP To include edit control in the tabbing order. 


See CreateEx in the CWnd base class for a full description of these window 
styles. 


Use any combination of the following edit control styles for dwStyle: 


Style Meaning 


ES_AUTOHSCROLL Automatically scrolls text to the right by 10 
characters when the user types a character at the 
end of the line. When the user presses the ENTER 
key, the control scrolls all text back to position 0. 


ES_AUTOVSCROLL Automatically scrolls text up one page when the 
user presses ENTER on the last line. 


ES_CENTER Centers text in a multiline edit control. 
ES_LEFT Aligns text flush-left. 
ES_LOWERCASE Converts all characters to lowercase as they are 


typed into the edit control. 
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CEdit::Create 


Style 
ES_MULTILINE 


ES_NOHIDESEL 


ES_OEMCONVERT 


Meaning 


Designates a multiple-line edit control. (The 
default is single-line.) If the 
ES_AUTOVSCROLL style is specified, the edit 
control shows as many lines as possible and scrolls 
vertically when the user presses the ENTER key. If 
ES_ AUTOVSCROLL is not given, the edit 
control shows as many lines as possible and beeps 
if ENTER is pressed when no more lines can be 
displayed. 


If the ES_AUTOHSCROLL style is specified, 
the multiple-line edit control automatically scrolls 
horizontally when the caret goes past the right 
edge of the control. To start a new line, the user 
must press ENTER. If ES_AUTOHSCROLL is not 
given, the control automatically wraps words to 
the beginning of the next line when necessary; a 
new line is also started if ENTER is pressed. The 
position of the wordwrap is determined by the 
window size. If the window size changes, the 
wordwrap position changes, and the text is 
redisplayed. 


Multiple-line edit controls can have scroll bars. An 
edit control with scroll bars processes its own 
scroll-bar messages. Edit controls without scroll 
bars scroll as described above, and process any 
scroll messages sent by the parent window. 


Normally, an edit control hides the selection when 
the control loses the input focus, and inverts the 
selection when the control receives the input focus. 
Specifying ES_NOHIDESEL deletes this default 
action. 


Text entered in the edit control is converted from 
the ANSI character set to the OEM character set 
and then back to ANSI. This ensures proper 
character conversion when the application calls the 
AnsiToOem Windows function to convert an 
ANSI string in the edit control to OEM characters. 
This style is most useful for edit controls that 
contain filenames. 


Return Value 


See Also 


Syntax 


Remarks 


See Also 
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Style Meaning 


ES_ PASSWORD Displays all characters as an asterisk (*) as they 
are typed into the edit control. An application can 
use the SetPasswordChar member function to 
change the character that is displayed. 


ES_ RIGHT Aligns text flush-right in a multiline edit control. 


ES_UPPERCASE Converts all characters to uppercase as they are 
typed into the edit control. 


Create returns TRUE if initialization is successful; FALSE if unsuccessful. 


CEdit::CEdit 


CEdit::Cut 
void CutQ); 


Deletes (cuts) the current selection (if any) in the edit control and copies the de- 
leted text to the Clipboard in CF_ TEXT format. 


The deletion performed by Cut can be undone by calling the Undo member 
function. 


To delete the current selection without placing the deleted text into the Clipboard, 
call the Clear member function. 


CEdit::Undo, CEdit::Clear, CEdit::Copy, CEdit::Paste, WM_CUT 
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Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CEdit::EmptyUndoBuffer 


void EmptyUndoBuffer(Q); 


Resets (clears) the undo flag of an edit control. The edit control will now be un-. 
able to undo the last operation. The undo flag is set whenever an operation within 
the edit control can be undone. 


The undo flag is automatically cleared whenever the SetWindowText or 
SetHandle member function is called. 


CEdit::CanUndo, CEdit::SetHandle, CEdit:: Undo, CWnd::SetWindowText, 
EM_EMPTYUNDOBUFFER 


CEdit::FmtLines 


BOOL FmtLines( BOOL bAddEOL ); 


bAddEOL 
Specifies whether soft line-break characters are to be inserted. A value of 
TRUE inserts the characters; a value of FALSE removes them. 


Sets the inclusion of soft line-break characters on or off within a multiple-line edit 
control. A soft line break consists of two carriage returns and a linefeed inserted at 
the end of a line that is broken because of word wrapping. A hard line break con- 
sists of one carriage return and a linefeed. Lines that end with a hard line break are 
not affected by FmtLines. 


Windows will only respond if the CEdit object is a multiple-line edit control. 
FmtLines only affects the buffer returned by GetHandle and the text returned by 


WM_GETTEXT. It has no impact on the display of the text within the edit 
control. 


TRUE if any formatting occurs; otherwise FALSE. 


CEdit::GetHandle, CWnd::GetWindowText, EM_FMTLINES 


Syntax 


Remarks 


Return Value 
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Syntax 
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CEdit::GetHandle 


HANDLE GetHandle() const; 


Retrieves a handle to the memory currently allocated for a multiple-line edit con- 
trol. The handle is a local memory handle and may be used by any of the Local 
Windows memory functions that take a local memory handle as a parameter. 


GetHandle is only processed by multiple-line edit controls. 


Call GetHandle for a multiple-line edit control in a dialog box only if the 
dialog box was created with the DS_LOCALEDIT style flag set. If the 
DS_LOCALEDIT style is not set, you will still get a nonzero return value, 
but you will not be able to use the returned value. 


A local memory handle that identifies the buffer that holds the contents of the edit 
control. If an error occurs, such as sending the message to a single-line edit con- 
trol, the return value is 0. 


CEdit::SetHandle, EM_GETHANDLE 


CEdit::GetLine 


int GetLine( int n/ndex, LPSTR [pBuffer ) const; 


int GetLine( int n/ndex, LPSTR /pBuffer, int nMaxLength ) const; 


nIndex 
Specifies the line number to retrieve from a multiple-line edit control. Line 
numbers are zero-based; a value of 0 specifies the first line. This parameter is 
ignored by a single-line edit control. 


lpBuffer 
Points to the buffer that receives a copy of the line. The first word of the buffer 
must specify the maximum number of bytes that can be copied to the buffer. 


nMaxLength 
Specifies the maximum number of bytes that can be copied to the buffer. 
GetLine places this value in the first word of [pBuffer before making the call 
to Windows. 
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Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Retrieves a line of text from an edit control and places it in [pBuffer. This call is 
not processed for a single-line edit control. 


The copied line does not contain a null-termination character. 


The number of bytes actually copied. The return value is 0 if the line number 
specified by nIndex is greater then the number of lines in the edit control. 


CEdit::LineLength, CWnd::GetWindowText, EM_GETLINE 


CEdit::GetLineCount 


int GetLineCount() const; 


Retrieves the number of lines in a multiple-line edit control. 


GetLineCount is only processed by multiple-line edit controls. 


An integer containing the number of lines in the multiple-line edit control. If no 
text has been entered into the edit control, the return value is 1. 


EM_GETLINECOUNT 


CEdit::GetModify 


BOOL GetModify() const; 


Determines if the contents of an edit control have been modified. 


Windows maintains an internal flag indicating whether the contents of the edit con- 
trol have been changed. This flag is cleared when the edit control is first created, 
and may also be cleared by calling the SetModify member function. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


see Also © 


Syntax 


Remarks 


Return Value 


See Also 
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TRUE if the edit-control contents have been modified; FALSE if they have re- 
mained unchanged. 


CEdit::SetModify, EM_GETMODIFY 


CEdit::GetRect 


void GetRect( LPRECT /pRect ) const; 


[pRect 
Points to the RECT structure that receives the formatting rectangle. 


Gets the formatting rectangle of an edit control. The formatting rectangle is the 
limiting rectangle of the text, which is independent of the size of the edit-control 
window. 


The formatting rectangle of a multiple-line edit control can be modified by the 
SetRect and SetRectNP member functions. 


CEdit::SetRect, CEdit::SetRectNP, EM_GETRECT 


CEdit::GetSel 


DWORD GetSel() const; 


Gets the starting and ending character positions of the current selection (if any) in 
an edit control. 


A 32-bit value that contains the starting position in the low-order word and the 
position of the first nonselected character after the end of the selection in the high- 


order word. 


CEdit::SetSel, EM_ GETSEL 
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Parameters 


Remarks 


See Also 
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Parameters 


Remarks 


Return Value 


See Also 


CEdit::LimitText 
void LimitText( int nChars = 0 ); 


nChars 
Specifies the length (in bytes) of the text that the user can enter. If this parame- 
ter is O, the text length is set to 65,535 bytes. This is the default behavior. 


Limits the length of the text that the user may enter into an edit control. 


LimitText only limits the text the user can enter. It has no effect on any text al- 
ready in the edit control when the message is sent, nor does it affect the length of 
the text copied to the edit control by the SetWindowText member function in 
CWhnd. . 


CWnd::SetWindowText, EM_LIMITTEXT 


CEdit::LineFromChar 


int LineFromChar( int n/ndex = —1 ) const; 


nindex 
Contains the zero-based index value for the desired character in the text of the 
edit control, or contains —1. If n/ndex is —1, it specifies the current line, 1.e., the 
line that contains the caret. 


Retrieves the line number of the line that contains the specified character index. A 
character index is the number of characters from the beginning of the edit control. 


This member function is only used by multiple-line edit controls. 


The zero-based line number of the line containing the character index specified by 
nindex. If nIndex is —1, the number of the line that contains the first character of 
the selection is returned. If there is no selection, the current line number is 
returned. 


CEdit:: LineIndex, EM_LINEFROMCHAR 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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Parameters 


Remarks 
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CEdit::Linelndex 


int LineIndex( int nLine = —1 ) const; 


nLine 
Contains the index value for the desired character in the text of the edit control, 
or contains —1. If nLine is —1, it specifies the current line, 1.e., the line that con- 
tains the caret. 


Retrieves the character index of a line within a multiple-line edit control. The char- 
acter index is the number of characters from the beginning of the edit control to 
the specified line. 


This member function is only processed by multiple-line edit controls. 


The character index of the line specified in nLine, or —1 if the specified line num- 
ber is greater then the number of lines in the edit control. 


CEdit::_LineFromChar, EM_LINEINDEX 


CEdit::LineLength 


int LineLength( int nLine = —1 ) const; 


nLine 
Specifies the character index of a character in the line whose length is to be re- 
trieved. If this parameter is —1, the length of the current line (the line that con- 
tains the caret) is returned, not including the length of any selected text within 
the line. 


When LineLength is called for a single-line edit control, this parameter is 
ignored. 


Retrieves the length of a line in an edit control. 


Use the LineIndex member function to retrieve a character index for a given line 
number within a multiple-line edit control. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


When LineLength is called for a multiple-line edit control, the return value is the 
length (in bytes) of the line specified by nLine. When LineLength is called for a 
single-line edit control, the return value is the length (in bytes) of the text in the 
edit control. 


CEdit::_LineIndex, EM_LINELENGTH 


CEdit::LineScroll 


void LineScroll( int nLines, int nChars = 0 ); 


nLines 
Specifies the number of lines to scroll vertically. 


nChars 
Specifies the number of character positions to scroll horizontally. 


Scrolls the text of a multiple-line edit control. 
This member function is only processed by multiple-line edit controls. 


The edit control will not scroll vertically past the last line of text in the edit con- 
trol. If the current line plus the number of lines specified by nLines exceeds the 
total number of lines in the edit control, the value will be adjusted such that the 
last line of the edit control is scrolled to the top of the edit-control window. 


LineScroll can be used to scroll horizontally past the last character of any line. 


A call to this member function will be ignored if the multiple-line edit control was 
not created with the ES_LEFT style. 


EM_LINESCROLL 


Syntax 


Remarks 


See Also 
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Remarks 


See Also 


Syntax 
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CEdit::Paste 


void PasteQ); 


Inserts the data from the Clipboard into the edit control at the current cursor posi- 
tion. Data is inserted only if the Clipboard contains data in CF_TEXT format. 


CEdit::Clear, CEdit::Copy, CEdit::Cut, WM_ PASTE 


CEdit::ReplaceSel 


void ReplaceSel( const char FAR* /pNewText ); 


lpNewText 
Points to a null-terminated string containing the replacement text. 


Replaces the current selection in an edit control with the text specified by 
[lpNewText. 


Replaces only a portion of the text in an edit control. If you want to replace all of 
the text, use the CWnd::SetWindowText member function. 


If there is no current selection, the replacement text is inserted at the current cursor 
location. 


CWnd::SetWindowText, EM_REPLACESEL 


CEdit::SetHandle 


void SetHandle( HANDLE /Buffer ); 


hBuffer 
Contains a handle to the local memory. This handle must have been cre- 
ated by a previous call to the LocalAlloc Windows function using the 
LMEM_MOVEABLE flag. The memory is assumed to contain a null- 
terminated string—if this is not the case, the first byte of the allocated memory 
should be set to 0. 
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Remarks Sets the handle to the local memory that will be used by a multiple-line edit con- 
trol. The edit control will then use this buffer to store the currently displayed text 
instead of allocating its own buffer. 


This member function is only processed by multiple-line edit controls. 


Before an application sets anew memory handle, it should use the GetHandle 
member function to get the handle to the current memory buffer and free that 
memory using the Windows LocalFree function. 


SetHandle clears the undo buffer (the CanUndo member function then returns 
FALSE) and the internal modification flag (the GetModify member function then 
returns FALSE). The edit-control window will be redrawn. 


You may use this member function in a multiple-line edit control in a dialog box 
only if you have created the dialog box with the DS_LOCALEDIT style flag set. 


See Also | CEdit::CanUndo, CEdit::GetHandle, CEdit::GetModify, ::LocalAlloc, 
::LocalFree, EM_SETHANDLE 


CEdit::SetModify 


Syntax void SetModify( BOOL bModified = TRUE ); 


Parameters bModified | 
A value of TRUE indicates that the text has been modified, and a value of 
FALSE indicates it is unmodified. By default, the modify flag is set. 


Remarks Sets or clears the modification flag for an edit control. The modification flag indi- 
cates whether or not the text within the edit control has been modified. It is auto- 
matically set whenever the user changes the text. Its value may be retrieved with 
the GetModify member function. 


See Also CEdit::GetModify, EM_SETMODIFY 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 
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CEdit::SetPasswordChar 


void SetPasswordChar( char ch ); 


ch 
Specifies the character to be displayed in place of the character typed by the 
user. If ch is O, the actual characters typed by the user are displayed. 


Sets or removes a password character displayed in an edit control when the user 
enters text. When a password character 1s set, that character is displayed for each 
character the user types in. 


This member function has no effect on a multiple-line edit control. 


When the SetPasswordChar member function ts called, CEdit will redraw all 
visible characters using the character specified by ch. 


If the edit control is created with the ES_ PASSWORD style, the default pass- 
word character is set to an asterisk (*). This style is removed if SetPasswordChar 
1s called with ch set to 0. 


EM_SETPASSWORDCHAR 


CEdit::SetRect 


void SetRect( LPRECT /pRect ); 


lpRect 
Points to the RECT or CRect that specifies the new dimensions of the format- 
ting rectangle. 


Sets the dimensions of a rectangle using the specified coordinates. This call is only 
processed by a multiline edit control. 


Use SetRect to set the formatting rectangle of a multiple-line edit control. The for- 
matting rectangle is the limiting rectangle of the text, which is independent of the 
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See Also 


Syntax 


Parameters 


Remarks 


See Also 


size of the edit-control window. When the edit control is first created, the format- 
ting rectangle is the same as the client area of the edit-control window. By using 
the SetRect member function, an application can make the formatting rectangle 
larger or smaller then the edit-control window. 


If the edit control has no scroll bar, text will be clipped, not wrapped, if the format- 
ting rectangle is made larger than the window. 


When SetRect is called, the edit control’s text is also reformatted and redisplayed. 


CRect::CRect, CRect::CopyRect, CRect::operator =, CRect::SetRectEmpty, 
CEdit::GetRect, CEdit::SetRectNP, EM_SETRECT 


CEdit::SetRectNP 


void SetRectNP( LPRECT I[pRect ); 


lpRect 
Points to a RECT or CRect that specifies the new dimensions of the rectangle. 


Sets the formatting rectangle of a multiple-line edit control. The formatting rec- 
tangle is the limiting rectangle of the text, which is independent of the size of the 
edit-control window. When the edit control is first created, the formatting rec- 
tangle is the same as the client area of the edit-control window. By calling the 
SetRectNP member function, an application can make the formatting rectangle 
larger or smaller then the edit-control window. 


If the edit control has no scroll bar, text will be clipped, not wrapped, if the format- 
ting rectangle is made larger than the window. 


SetRectNP is identical to the SetRect member function except that the edit- 
control window is not redrawn. 


This member is only processed by multiple-line edit controls. 


CRect::CRect, CRect::CopyRect, CRect::operator =, CRect::SetRectEmpty, 
CEdit::GetRect, CEdit::SetRect, EM_SETRECT 
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Remarks 
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Parameters 
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CEdit::SetSel 


void SetSel( DWORD dwSelection ); 


void SetSel( int nStartChar, int nEndChar ); 


dwSelection 
Specifies the starting position in the low-order word and the ending position in 
the high-order word. If the low-order word is 0 and the high-order word is —1, 
all the text in the edit control is selected. If the low-order word is —1, any cur- 
rent selection is removed. 


nStartChar 
Specifies the starting position. If nStartChar is 0 and nEndChar is —1, all the 
text in the edit control is selected. If nStartChar is —1, any current selection 1s 
removed. 


nEndChar 
Specifies the ending position. 


Selects a range of characters in an edit control. The edit control does not display 
the selection set by this member function as it does when the user makes a 
selection. 


CEdit::GetSel, CEdit::ReplaceSel, EM_SETSEL 


CEdit::SetfabStops 


BOOL SetTabStops( int n7abStops, LPINT rgTabStops ); 
void SetTabStopsQ); 
BOOL SetTabStops( int cxEachStop ); 


nTabStops 
Specifies the number of tab stops contained in rgTabStops. If this parameter is 
greater then 1, then rgTabStops points to an array of tab stops. 


rg TabStops 
Points to an array of unsigned integers specifying the tab stops in dialog units. 
If nTabStops is 1, this parameter points to an unsigned integer containing the 
distance between all tab stops (in dialog units). 


302 CEdit::Undo 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


cxEachStop 
Specifies that tab stops are to be set at every cxEachStop dialog units. 


Sets the tab stops in a multiple-line edit control. When text is copied to a multiple- 
line edit control, any tab character in the text will cause space to be generated up 
to the next tab stop. 


If nTabStops is 0, rgTabStops is ignored and default tab stops are set at every 32 
dialog units. 


This member function is only processed by multiple-line edit controls. 
SetTabStops does not automatically redraw the edit window. If the application is 


changing the tab stops for text already in the edit control, it needs to call 
CWnd::InvalidateRect to redraw the edit window. 


TRUE if the tabs were set; otherwise FALSE. 


::GetDialogBaseUnits, CWnd::InvalidateRect, EM_SETTABSTOPS 


CEdit::Undo 


BOOL Undo(Q; 


Use to undo the last edit-control operation. 


An undo operation can also be undone. For example, you can restore deleted text 
with the first call to Undo, and remove the text again with a second call to Undo 
as long as there is no intervening edit operation. 


For a single-line edit control, the return value is always TRUE. For a multiple-line 
edit control, the return value is TRUE if the undo operation is successful, or 
FALSE if the undo operation fails. 


CEdit::CanUndo, EM_UNDO 
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class CException : public CObject 


Comments 


Derivation 


CException is the base class for all exceptions in the 
Microsoft Foundation Class Library. The derived 
classes are listed below: 


/ 7 
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CException 


Class Description 

CMemoryException Out-of-memory exception 
CNotSupportedException Request for an unsupported operation 
CArchiveException Archive-specific exceptions 
CFileException File-specific exceptions 
CResourceException Windows resource not found or not creatable 


These exceptions are intended to be used with the THROW, THROW_LAST, 
TRY, CATCH, AND_CATCH, and END_ CATCH macros. For more informa- 
tion on exception processing, see Chapter 5, “Exception Processing.” Also see the 
cookbook in the Class Libraries User’s Guide. 


#include <afx.h> 


Use the derived classes to catch specific exceptions. Use CException if you need 
to catch all types of exceptions (and then use CObject::IsKindOf to differentiate 
among classes derived from CException.) All derived CException classes use the 
IMPLEMENT_DYNAMIC macro. 


CException objects are deleted automatically. Do not delete them yourself. 


Because CException is an abstract base class, you cannot create CException ob- 
jects; you must create objects of derived classes. If you need to create your own 
CException type, use one of the derived classes listed above as a model. 
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class CFile : 


See Also 


Public Members 


public CObject 


CFile is the base class for Foundation class files. It 
directly provides unbuffered, binary disk input/out- 
put services, and it indirectly supports text files and 
memory files through its derived classes. CFile 
works in conjunction with the CArchive class to support archiving of Foundation 
objects. 


Le 


CObject | 


LOL 


LO OTTO 


The hierarchical relationship between this class and its derived classes allows your 
program to operate on all file objects through the polymorphic CFile interface. A 
memory file, for example, behaves like a disk file. 


Use CFile and its derived classes for general-purpose disk I/O. Use ofstream or 
other I/O stream classes for formatted text sent to a disk file. 


Normally, a disk file is opened automatically on CFile construction and closed on 
destruction. Static member functions permit you to interrogate file status without 
opening the file. 


#include <afx.h> . 


CStdioFile, CMemFile 


Data Members 


m_hFile Usually contains the operating-system file handle. 


Construction/Destruction 


CFile Constructs a CFile object from a path or file 
handle. 

~CFile Destroys the object, closing the file if it is open. 

Duplicate Constructs a duplicate object based on this file. 

Open Safely opens a file with an error-testing option. 


Close Closes a file and deletes the object. 


Input/Output 
Read 


Write 


Flush 


Position 
Seek 
Seek ToBegin 


SeekToEnd 


GetLength 
SetLength 


Locking 
LockRange 
UnlockRange 


Status 
GetPosition 


GetStatus 


Static 
Rename 
Remove 
GetStatus 


SetStatus 
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Reads (unbuffered) data from a file at the current 
file position. 


Writes (unbuffered) data in a file to the current file 
position. 


Flushes any data yet to be written. 


Positions the current file pointer. 


Positions the current file pointer at the beginning 
of the file. 


Positions the current file pointer at the end of the 
file. 


Obtains the length of the file. 
Changes the length of the file. 


Locks a range of bytes in a file. 


Unlocks a range of bytes in a file. 


Gets the current file pointer. 


Obtains the status of this open file. 


Renames the specified file (static function). 
Deletes the specified file (static function). 


Obtains the status of the specified file (static, vir- 
tual function). 


Sets the status of the specified file (static, virtual 
function). 
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Member Functions 


CFile::CFile 
Syntax CFileQ; 
CFile( int hFile ); 


CFile( const char* pszFileName, UINT wOpenFlags ) 
throw( CFileException ); 


Parameters hFile 
The handle of a file that is already open. 


pszFileName 
A string that is the path to the desired file. The path may be relative or absolute. 


wOpenFlags 
Sharing and access mode. Specifies the action to take when opening the file. 
You can combine options listed below by using the bitwise-OR (| ) operator. 
One access permission and one share option are required; the modeCreate and 
modeNoInherit modes are optional. 


Value Meaning 

CFile::modeCreate Directs the constructor to create a new file. If 
the file exists already, it is truncated to 0 
length. 

CFile::modeRead Opens the file for reading only. 

CFile::modeRead Write Opens the file for reading and writing. 

CFile::modeWrite Opens the file for writing only. 

CFile::modeNoInherit Prevents the file from being inherited by 


child processes. 


CFile::shareDenyNone Opens the file without denying other 
processes read or write access to the file. 
Create fails if the file has been opened in 
compatibility mode by any other process. 


CFile::shareDenyRead Opens the file and denies other processes 
read access to the file. Create fails if the file 
has been opened in compatibility mode or 
for read access by any other process. 


Remarks 
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Value Meaning 


CFile::shareDenyWrite Opens the file and denies other processes 
write access to the file. Create fails if the file 
has been opened in compatibility mode or 
for write access by any other process. 


CFile::shareExclusive Opens the file with exclusive mode, denying 
other processes both read and write access to 
the file. Construction fails if the file has been 
opened in any other mode for read or write 
access, even by the current process. 


CFile::shareCompat Opens the file with compatibility mode, 
allowing any process on a given machine to 
open the file any number of times. 
Construction fails if the file has been opened 
with any of the other sharing modes. 


CFile::typeText Sets text mode with special processing for 
carriage return—linefeed pairs (used in 
derived classes only). 


CFile::typeBinary Sets binary mode (used in derived classes 
only). 


The default constructor does not open a file, but rather sets m_hFile to 
CFile::hFileNull. Because this constructor does not throw an exception, it does 
not make sense to use TRY/CATCH logic. Use the Open member function, then 
test directly for exception conditions. For a discussion of exception processing 
strategy, see the cookbook in the Class Libraries User’s Guide. 


The constructor with one argument creates a CFile object that corresponds to an 
existing operating-system file identified by hFile. No check is made on the access 
mode or file type. 


The constructor with two arguments creates a CFile object and opens the corre- 
sponding operating-system file with the given path. This constructor combines the 
functions of the first constructor and the Open member function. It throws an ex- 
ception if there is an error while opening the file. Generally this means that the 
error is unrecoverable and that the user should be alerted. 
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Example 


syntax 


Remarks 


Syntax 


Remarks 


See Also 


CFile::~CFile 


char* pFileName = “test.dat"; 
TRY 
{ 
CFile f( pFileName, CFile::modeCreate | CFile::modeWrite ); 
} 
CATCH( CFileException, e ) 
{ 
ifdef _ DEBUG 
afxDump << "File could not be opened " << e->m_cause << "\\n"; 
dtendif 
} 
END_ CATCH 


CFile::~CFile 
virtual ~CFileQ; 


This destructor closes the operating-system file if it is open. 


CFile::Close 


virtual void Close() 
throw( CFileException ); 


Closes the file associated with this object and makes the file unavailable for read- 
ing or writing. If you have not closed the file before destroying the object, the de- 
structor closes it for you. 


If you used new to allocate the CFile object on the heap, then you must delete it 
after closing the file. Close sets m_hFile to CFile::hFileNull. 


CFile::Open 
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CFile::Duplicate 


Syntax virtual CFile* Duplicate() const 
throw( CFileException ); 


Remarks Constructs a duplicate CFile object for a given file. This is equivalent to the C run- 
time function dup. 


Example extern CFile* cfilel; 
CFile* cfile2 = cfilel->Duplicate(); 


CFile::Flush 


Syntax virtual void Flush() 
throw( CFileException ); 


Remarks Forces any data remaining in the file buffer to be written to the file. 


The use of Flush does not guarantee flushing of CArchive buffers. If you are 
using an archive, call CArchive::Flush first. 


CFile::GetLength 


Syntax virtual DWORD GetLength() const 
throw( CFileException ); 


Remarks Obtains the current logical length of the file in bytes, not the amount physically 
allocated. 
Return Value The length of the file. 


See Also CFile::SetLength 
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CFile::GetPosition 


Syntax virtual DWORD GetPosition() const 
throw( CFileException ); 


Remarks Obtains the current value of the file pointer, which can be used in subsequent calls 
to Seek. 

Return Value The file pointer as a 32-bit double word. 

Example extern CFile cfile; 


DWORD dwPosition = cfile.GetPosition(); 


CFile::GetStatus 


Syntax virtual BOOL GetStatus( CFileStatus& rStatus ) const; 


static BOOL GetStatus( const char* pszFileName, 
CFileStatus& rStatus ) const; 


Parameters rStatus 
A reference to a user-supplied CFileStatus structure that will receive the status 
information. The CFileStatus structure has the following fields: 


Field Meaning 

CTime m_ctime The date and time the file was 
created 

CTime m_mtime The date and time the file was 


last modified 


CTime m_atime The date and time the file was 
last accessed for reading 


LONG m_ size The logical size in bytes of the 
file, as reported by the MS-DOS 
command dir 


Remarks 


Return Value 
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Field Meaning 
BYTE m_attribute The MS-DOS attribute byte of 
the file 


char m_szFullName[_MAX_ PATH] The absolute filename 
(_MAX_ PATH is defined in 
stdlib.h) 


pszFileName 
A string that is the path to the desired file. The path may be relative or absolute, 
but may not contain a network name. 


The virtual version of GetStatus retrieves the status of the open file associated 
with this CFile object. It does not insert a value into the m_szFullName structure 
member. 


The static version gets the status of the named file and copies the filename to 
m_szFullName. This function obtains the file status from the directory entry 
without actually opening the file. It is useful for testing the existence and access 
rights of a file. 


The m_attribute is the MS-DOS file attribute. The Microsoft Foundation classes 
provide an enum type attribute so that you can specify attributes symbolically: 


enum Attribut { 


normal = Qx@Q, 
readOnly = 0@x@l1, 
hidden = Qx02, 
System = 0x04, 
volume = 0x8, 
directory = @xlQ, 
archive = @x20 
Pe 


TRUE if no error, in which case rStatus is valid; otherwise FALSE. FALSE indi- 
cates that the file does not exist. 
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Example 


See Also 
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CFileStatus status; 
extern CFile cfile; 


if( cfile.GetStatus(status) ) // virtual member function 
{ 
dHifdef _DEBUG 
afxDump << "File size = " << status.m_size << "\\n"; 
dtendif 


} 
char* pFileName “test.dat"; 
if( CFile::GetStatus( pFileName, status) ) // static function 
{ 
ifdef _ DEBUG 


afxDump << "Full file name = " << status.m_szFullName << "\\n"; 
dtendif 
} 
CFile::SetStatus 


CFile::LockRange 


virtual void LockRange( DWORD dwPos, DWORD dwCount ) 
throw( CFileException ); 


dwPos 
The byte offset of the start of the byte range to lock. 


dwCount 
The number of bytes in the range to lock. 


Locks a range of bytes in an open file, throwing an exception if the file is already 


locked. Locking bytes in a file prevents access to those bytes by other processes. 
You can lock more than one region of a file, but no overlapping regions are 
allowed. 


When you unlock the region, using the UnockRange member function, the byte 
range must correspond exactly to the region that was previously locked. The 
LockRange function does not merge adjacent regions; if two locked regions are 
adjacent, you must unlock each region separately. 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 
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Under MS-DOS, you must load SHARE.EXE; otherwise, the function throws a 
CFileException object. 


Note This function is not available for the CMemFile-derived class. 


extern DWORD dwPos; 

extern DWORD dwCount; 

extern CFile cfile; 
cfile.LockRange( dwPos, dwCount ); 


CFile::UnlockRange 


CFile::Open 


virtual BOOL Open( const char* pszFileName, UINT wStyleFlags, 
CFileException* pError = NULL ); 


pszFileName 
A string that is the path to the desired file. The path may be relative or absolute, 
but may not contain a network name. 


wStyleFlags 
A WORD that defines the file’s sharing and access mode. It specifies the ac- 
tion to take when opening the file. You can combine options by using the 
bitwise-OR (|) operator. One access permission and one share option are re- 
quired; the modeCreate and modeNoInherit modes are optional. See the 
CFile constructor for a list of mode options. 


pError 
A pointer to an existing file-exception object that indicates the completion 
status of the open operation. 


Open is designed for use with the default CFile constructor. The two functions 
form a “safe” method for opening a file where a failure is a normal, expected con- 
dition. The constructor is guaranteed to succeed, and Open returns (a pointer to) 
an exception object, bypassing the THROW/TRY/CATCH mechanism. Thus 
there is no possibility of a memory leak due to a failing constructor. 


TRUE if the open was successful; otherwise FALSE. The pError parameter is 
only meaningful if FALSE is returned. 
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Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


CFile f; 
CFileException e; 
char* pFileName "test.dat"; 
if( !f.Open( pFileName, CFile::modeCreate | CFile::modeWrite, &e ) ) 
{ 
#ifdef _DEBUG 
afxDump << "File could not be opened ™ << e.m_cause << "\\n"; 
Htendif 


CFile::CFile, CFile::Close 


CFile::Read 


virtual UINT Read( void FAR* [pBuf, UINT nCount ) 
throw( CFileException ); 


lpBuf 
Pointer to the user-supplied buffer that is to receive the data read from the file. 


nCount 
The maximum number of bytes to be read from the file. For text-mode files, 
carriage return—linefeed pairs are counted as single characters. 


Reads data into a buffer from the file associated with the CFile object. 


The number of bytes transferred to the buffer. 


Note For all CFile classes, the return value may be less than nCount if the end of 
file was reached. 


extern CFile cfile; 
char pbuf[10@]; 
WORD nBytesRead = cfile.Read( pbuf, 100 ); 


CFile:: Write 


Syntax 


Parameters 


Remarks 


Example 


Syntax 


Parameters 


Remarks 
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CFile::Remove 


static void Remove( const char* pszFileName ) 
throw( CFileException ); 


pszFileName 
A string that is the path to the desired file. The path may be relative or absolute, 
but may not contain a network name. 


This static function deletes the file specified by the path. It will not remove a 
directory. 


The Remove member function throws an exception if the file is connected to an 
existing open file or if the file cannot be removed. This is equivalent to the 
MS-DOS del command. 


char* pFileName = "test.dat”; 
TRY 
{ 

CFile::Remove( pFileName ); 
} 
CATCH( CFileException, e ) 
{ 


dFifdef _ DEBUG 
afxDump << "File " << pFileName << " not found\\n"; 
#tendi f 


I 
END _ CATCH 


CFile::Rename 


static void Rename( const char* pszOldName, const char* pszNewName ) 
throw( CFileException ); 


pszOldName 
The old path. 


pszNewName 
The new path. 


This static function renames the specified file. Directories cannot be renamed. 
This is equivalent to the MS-DOS ren command. 
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Example 


Syntax 


Parameters 


Remarks 


extern char* p0OldName; 
extern char* pNewName; 


TRY 
{ 
CFile::Rename( pOldName, pNewName ); 
} 
CATCH( CFileException, e ) 
{ 


#Fifdef _DEBUG 
afxDump << "File " << pOldName << ™" not found, cause = 
<< e->m_cause << "\\n"; 
dtendif 
} 
END_CATCH 


CFile::Seek 


virtual LONG Seek( LONG /Off, UINT wFrom ) 
throw( CFileException ); 


lOff 


Number of bytes to move the pointer. 


wFrom 
Pointer movement mode. Must be one of the following: 


Value Meaning 

CFile: :begin Move the file pointer /Off bytes forward from the 
beginning of the file. 

CFile::current Move the file pointer /Off bytes from the current 
position in the file. 

CFile::end Move the file pointer /Off bytes from the end of the 
file. 


Repositions the pointer in a previously opened file. The Seek function permits ran- 
dom access to a file’s contents by moving the pointer a specified amount, abso- 


lutely or relatively. No data is actually read during the seek. 


When a file is opened, the file pointer is positioned at offset 0, the beginning of 


the file. 


Return Value 


Example 


syntax 


Remarks 


Example 


Syntax 


Remarks 


Return Value 


Example 


See Also 
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If the requested position is legal, Seek returns the new byte offset from the begin- 
ning of the file. Otherwise, the return value is undefined, and a CFileException 
object is thrown. 


extern CFile cfile; 
LONG 10ffset = 1000, lActual; 
1Actual = cfile.Seek( l10ffset, CFile::begin ); 


CFile::SeekToBegin 


void SeekToBegin(Q) 
throw( CFileException ); 


Sets the value of the file pointer to the beginning of the file. SeekToBegin() is 
equivalent to Seek(OL, CFile::begin). 


extern CFile cfile; 
cfile.SeekToBegin(); 


CFile::SeekToEnd 


DWORD SeekToEnd() 
throw( CFileException ); 


Sets the value of the file pointer to the logical end of the file. Seek ToEnd() is 
equivalent to CFile::Seek(OL, CFile::end). 


The length of the file in bytes. 


extern CFile cfile; 
DWORD dwActual = cfile.SeekToEnd(); 


CFile::GetLength, CFile::Seek, CFile::SeekToBegin 
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Syntax 


Parameters 


Remarks 


Example 


Syntax 


Parameters 


Remarks 


CFile::SetLength 


virtual void SetLength( const DWORD dwNewLen ) 
throw( CFileException ); 


dwNewLen 
Desired length of the file in bytes. This value may be larger or smaller than the 
current length of the file. The file will be extended or truncated as appropriate. 


Changes the length of the file. 


Note With CMemfFile, this function could throw a CMemoryException object. 


extern CFile cfile; 
DWORD dwNewLength = 10000; 
cfile.SetLength( dwNewLength ); 


CFile::SetStatus 


static void SetStatus( const char* pszFileName, const CFileStatus& status ) 
throw( CFileException ); 


pszFileName 
A string that is the path to the desired file. The path may be relative or absolute, 
but may not contain a network name. 


status 
The buffer containing the new status information. Call GetStatus to prefill the 
CFileStatus structure with current values, then make changes as required. If a 
value is 0, then the corresponding status item is not updated. See GetStatus for 
a description of the CFileStatus structure. 


Sets the status of the file associated with this file location. 
Under MS-DOS, all times in the CFileStatus structure contain the same value. 
To set the time, modify the m_mtime field of status. 


The SetStatus function will throw an exception under MS-DOS if the file’s read- 
only attribute is set. 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Example 


See Also 
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char*x pFileName = “test.dat"; 

extern BYTE newAttribute; 

CFileStatus status; 

CFile::GetStatus( pFileName, status ); 
status.m_attribute = newAttribute; 
CFile::SetStatus( pFileName, status ); 


CFile::GetStatus 


CFile::UnlockRange 


virtual void UnlockRange( const DWORD dwPos, const DWORD dwCount ) 
throw( CFileException ); 


dwPos 
The byte offset of the start of the byte range to unlock. 


dwCount 
The number of bytes in the range to unlock. 


Unlocks a range of bytes in an open file. See the description of LockRange for 
details. 


Under MS-DOS, you must load SHARE.EXE; otherwise, the function throws a 
CFileException object. 


Note This function is not available for the CMemFile-derived class. 


extern DWORD dwPos; 

extern DWORD dwCount; 

extern CFile cfile; 
cfile.UnlockRange( dwPos, dwCount ); 


CFile:: LockRange 
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Syntax 


Parameters 


Remarks 


Example 


See Also 


CFile::Write 


virtual void Write( const void FAR* /pBuf, UINT nCount ) 
throw( CFileException ); 


lpBuf 
A pointer to the user-supplied buffer that contains the data to be written to 
the file. 


nCount 
The number of bytes to be transferred from the buffer. For text-mode files, 
carriage return—linefeed pairs are counted as single characters. 


Writes data from a buffer to the file associated with the CFile object. 


Write throws an exception in response to several conditions, including the disk- 
full condition. 


extern CFile cfile; 
char pbuf[100]; 
cfile.Write( pbuf, 10@ ); 


CFile:: Read, CStdioFile:: WriteString 
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Data Members 


Syntax 


Remarks 


CFile::m_hFile 


UINT m_hFile; 


Contains the operating-system file handle for an open file. It contains 
CFile::m_hFileNull (an operating-system-independent empty file indicator) if the 
handle has not been assigned. 


Usage of m_hFile is not recommended because the member’s meaning depends 
on the derived class. m_hFile is made a public member to conveniently support 
nonpolymorphic use of the class. 
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Class CFileException : public CException 


See Also 


Comments 


Public Members 


A CFileException object represents a file-related ex- 
ception condition. The CFileException class includes 
public data members that hold the portable cause code 
and the operating-system-specific error number. The 
class also provides static member functions for throw- 
ing file exceptions and for returning cause codes for 
both operating-system errors and C run-time errors. 


#include <afx.h> 
CFile, Chapter 5, “Exception Processing” 


CFileException objects are constructed and thrown in CFile member functions 
and in member functions of derived classes. You can access these objects within 
the scope of a CATCH expression. For portability, use only the cause code to get 
the reason for an exception. 


Data Members 


m_ cause Contains portable code corresponding to the excep- 
tion cause. 

m_lOsError Contains the related operating-system error 
number. 


Construction/Destruction 
CFileException Constructs a CFileException object. 


Code Conversion 


OsErrorToException Returns a cause code corresponding to an 
MS-DOS error code. 
ErrnoToException Returns cause code corresponding to a run-time 


error number. 


Helper Functions 
ThrowOsError 


ThrowErrno 


CFileException 323 


Throws a file exception based on an operating- 
system error number. 


Throws a file exception based on a run-time error 
number. 


324  CFileException::CFileException 


Member Functions 


CFileException::CFileException 


Syntax CFileException( int cause = CFileException::none, LONG /OsError = -1 ); 


Parameters cause 
An enumerated type variable that indicates the reason for the exception. See 
CFileException::m_ cause for a list of the possible values. 


lOsError 
An operating-system-specific reason for the exception, if available. The 
/OsError parameter provides more information than cause provides. 


Remarks Constructs a CFileException object that stores the cause code and the operating- 
system code in the object. 


Do not use this constructor directly, but rather call the global function 
AfxThrowFileException. 


Note The variable /OsError avplies only to CFile and CStdioF ile obiects. The 
CMemfFile class does not handle this error code. More information specifically 
about the operating system is available through the run-time function _ dosexterr 
(MS-DOS only). 


See Also AfxThrowFileException 


CFileException::ErrnoToException 


Syntax Static int ErrnoToException( int nErrno ); 


Parameters nErrno 
An integer error code as defined in the run-time include file errno.h. 


Remarks This static function converts a given run-time library error value to a 
CFileException enumerated error value. See CFileException::m_ cause for a list 
of the possible enumerated values. 


Return Value Enumerated value that corresponds to a given run-time library error value. 


Example 


See Also 


Syntax 


Parameters 
Remarks 
Return Value 
Example 


See Also 


Syntax 


Parameters 


Remarks 


CFileException::ThrowErrno = 325 


#FHinclude <errno.h> 
ASSERT( CFileException::ErrnoToException( EACCES ) == 
CFileException::accessDenied ); 


CFileException::OsErrorToException 


CFileException::OsErrorToException 


static int OsErrorToException( LONG /OsError ); 


lOsError 
An operating-system-specific error code. 


This static function returns an enumerator that corresponds to a given lOsError 
value. If the error code is unknown, then the function returns 
CFileException:: generic. 


Enumerated value that corresponds to a given operating-system error value. 


ASSERT( CFileException::OsErrorToException( 5 ) == 
CFileException::accessDenied ); 


CFileException::ErrnoToException 


CFileException::ThrowErrno 


static void ThrowErrno( int nErrno ); 


nErrno 
An integer error code as defined in the run-time include file errno.h. 


This static function constructs a CFileException object corresponding to a given 
nErrno value, then throws the exception. 
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Example 


See Also 


Syntax 


Parameters 


Remarks 


Example 


See Also 


#Finclude <errno.h> 
CFileException::ThrowErrno( EACCES ); // “access denied" 


CFileException::ThrowOsError 


CFileException::ThrowOsError 


static void ThrowOsError( LONG /OsError ); 


lOsError 
An operating-system-specific error code. 


This static function throws a CFileException corresponding to a given /[OsError 
value. If the error code is unknown, then the function throws an exception coded 
as CFileException:: generic. 


CFileException::ThrowOsError( 5 ); // “access denied" 


CFileException::ThrowErrno 


Data Members 


Syntax 


Remarks 


CFileException::m_cause 


int m_ cause; 
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Contains values defined by a CFileException enumerated type. The enumer- 


ators are: 


Value 


CFileException: 
CFileException: 
CFileException:: 
CFileException:: 
CFileException:: 


CFileException: 
CFileException: 


CFileException: 


CFileException: 
CFileException: 


CFileException: 
CFileException: 


CFileException: 


CFileException: 
CFileException: 


shone 


:generic 


fileNotFound 
badPath 
tooManyOpenFiles 


saccessDenied 


sinvalidFile 
sremoveCurrentDir 


:directoryFull 
:sbadSeek 


shardIO 


:Sharing Violation 
lock Violation 


:diskFull 


endOfFile 


Meaning 


No error occurred. 

An unspecified error occurred. 
The file could not be located. 
All or part of the path is invalid. 


The permitted number of open files 
was exceeded. 


The file could not be accessed. 


There was an attempt to use an 
invalid file handle. 


Current working directory cannot be 
removed. 


There are no more directory entries. 


There was an error trying to set the 
file pointer. 


There was a hardware error. 


SHARE.EXE was not loaded, or 
shared region was locked. 


There was an attempt to lock a 
region that was already locked. 


The disk is full. 


The end of file was reached. 


Note These CFileException cause enumerators are distinct from the 


CArchiveException cause enumerators. 
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Example extern char* pFileName; 
: TRY 
{ 
CFile f( pFileName, CFile::modeCreate | CFile::modeWrite ); 
} 
CATCH( CFileException, e) 
{ 
if( e->m_cause == CFileException::fileNotFound ) 
printf( "ERROR: File not found\\n"); 
} 
END_CATCH 


CFileException::m_!OsError 


Syntax LONG m_1OsError; 


Remarks Contains the operating-system error code for this exception. See your operating- 
system technical manual for a listing of error codes. 


class CFont: 


Public Members 


CFont 329 


public CGdiObject 


The CFont class encapsulates a Windows graphical 
design interface (GDI) font and provides member func- 
tions for manipulating the font. To use a CF ont object, 
construct a CF ont object and attach a Windows font to 
it with CreateFont or CreateFontIndirect, and then 
use the object’s member functions to manipulate 

the font. 


Construction/Destruction 


CFont Constructs a CFont object. 

Initialization 

CreateFontIndirect Initializes a CFont object with the characteristics 
given ina LOGFONT structure. 

CreateFont Initializes a CFont with the specified charac- 
teristics. 

Operations 

FromHandle Returns a pointer to a CFont object when given a 


Windows HFONT. 
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Member Functions 


CFont::CFont 


Syntax CFont(); 


Remarks Constructs a CFont object. The resulting object must be initialized with 
CreateFont or CreateFontIndirect before it can be used. 


See Also CFont::CreateFontIndirect, CFont::CreateFont, ::EnumFonts 


CFont::CreateFont 


Syntax BOOL CreateFont( int nHeight, int nWidth, int nEscapement, int nOrientation, 
int nWeight, BYTE bitalic, BYTE bUnderline, BYTE cStrikeOut, 
BYTE nCharSet, BYTE nOutPrecision, BYTE nClinPrecision, BYTE nQuality 
BYTE nPitchAndFamily, const char FAR* [pFacename ); 


Parameters nHeight 
Specifies the desired height (in logical units) of the font. The font height can be 
specified in three ways. 


Height Result 

Greater than 0 Height is transformed into device units and matched 
against the cell height of the available fonts. 

Equal to 0 A reasonable default size is used. 

Less than 0 Height is transformed into device units and the absolute 


value is matched against the character height of the 
available fonts. 


For all height comparisons, the font mapper looks for the largest font that does 
not exceed the requested size. Then, if there is no such font, it looks for the 
smallest font available. 
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nWidth 
Specifies the average width (in logical units) of characters in the font. If nWidth 
is O, the aspect ratio of the device will be matched against the digitization 
aspect ratio of the available fonts to find the closest match, which is determined 
by the absolute value of the difference. 


nEscapement 
Specifies the angle (in 0.1-degree units) between the escapement vector and the 
x-axis of the display surface. The escapement vector is the line through the 
origins of the first and last characters on a line. The angle 1s measured counter- 
clockwise from the x-axis. 


nOrientation 
Specifies the angle (in 0.1-degree units) between the baseline of a character and 
the x-axis. The angle is measured counterclockwise from the x-axis. 


nWeight 
Specifies the font weight (in inked pixels per 1000). Although nWeight can be 
any integer value from 0 to 1000, the common values are as follows: 


Value Meaning 
400 Normal 
700 Bold 


These values are approximate; the actual appearance depends on the typeface. 
If nWeight is 0, a default weight is used. 


bItalic 
Specifies whether the font is italic. 


bUnderline 
Specifies whether the font is underlined. 


cStrikeOut 
Specifies whether characters in the font are struck out. Specifies a strikeout font 
if set to a nonzero value. 


nCharSet 
Specifies the font’s character set. The following values are predefined: 


ANSI CHARSET 
OEM_CHARSET 
SYMBOL_CHARSET 


The OEM character set is system-dependent. 


Fonts with other character sets may exist in the system. An application that uses 
a font with an unknown character set must not attempt to translate or interpret 
strings that are to be rendered with that font. Instead, the strings should be 
passed directly to the output device driver. 
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nOutPrecision 
Specifies the desired output precision. The output precision defines how closely 
the output must match the requested font’s height, width, character orientation, 
escapement, and pitch. It can be any one of the following values: 


OUT_CHARACTER_PRECIS 
OUT_DEFAULT_PRECIS 
OUT_STRING_PRECIS 
OUT_STROKE_PRECIS 


nClipPrecision 
Specifies the desired clipping precision. The clipping precision defines how to 
clip characters that are partially outside the clipping region. It can be any one of 
the following values: 


CLIP_CHARACTER_PRECIS 
CLIP_DEFAULT_PRECIS 
CLIP_STROKE_PRECIS 


nQuality 
Specifies the font’s output quality, which defines how carefully GDI must at- 
tempt to match the logical-font attributes to those of an actual physical font. It 
can be one of the following values: 


Value Meaning 
DEFAULT_QUALITY Appearance of the font does not matter. 
DRAFT_ QUALITY Appearance of the font is less important than 


when PROOF_QUALITY is used. For GDI 
raster fonts, scaling is enabled. Bold, italic, 
underline, and strikeout fonts are synthesized 
if necessary. 


PROOF_QUALITY Character quality of the font is more 
important than exact matching of the logical- 
font attributes. For GDI raster fonts, scaling 
is disabled and the font closest in size is 
chosen. Bold, italic, underline, and strikeout 
fonts are synthesized if necessary. 


nPitchAndFamily 
Specifies the pitch and family of the font. The two low-order bits specify the 
pitch of the font and can be any one of the following values: 


DEFAULT_ PITCH 
FIXED_ PITCH 
VARIABLE_ PITCH 


The four high-order bits of the member specify the font family and can be one 
of the following values: 


Remarks 


Return Value 


See Also 
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Value Meaning 

FF_DECORATIVE Novelty fonts. Old English, for example. 
FF_DONTCARE Don’t care or don’t know. 

FF_MODERN Fonts with constant stroke width (fixed-pitch), 


with or without serifs. Fixed-pitch fonts are 
usually modern. Pica, Elite, and Courier New 
are examples. 


FF_ROMAN Fonts with variable stroke width (proportionally 
spaced) and with serifs. Times New Roman and 
Century Schoolbook are examples. 


FF_SCRIPT Fonts designed to look like handwriting. Script 
and Cursive are examples. 


FF_SWISS Fonts with variable stroke width (proportionally 
spaced) and without serifs. MS Sans Serif is an 
example. 


An application can specify a value for nPitchAndFamily by using the Boolean _ 
OR operator to join a pitch constant with a family constant. 


Font families describe the look of a font in a general way. They are intended for 
specifying fonts when the exact typeface desired is not available. 


[pFacename 
A CString or pointer to a null-terminated string that specifies the typeface 
name of the font. The length of this string must not exceed 30 characters. The 
Windows EnumFonts function can be used to enumerate all currently available 
fonts. If JpFacename is NULL, GDI uses a default typeface. 


Initializes a CFont object with the specified characteristics. The font can sub- 
sequently be selected as the font for any device context. 


The CreateFont function does not create anew Windows GDI font. It merely 
selects the closest match from the fonts available in GDI’s pool of physical fonts. 


TRUE if successful; otherwise FALSE. 


CFont::CreateFontIndirect, ::CreateFont, :;:EnumFonts 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CFont::CreateFontindirect 
BOOL CreateFontIndirect( LPLOGFONT [pLogFont ); 


lpLogFont 
Points to a LOGFONT structure that defines the characteristics of the 
logical font. 


The LOGFONT structure has the following form: 


typedef struct tagLOGFONT { 
int lfHeight; 
int lfWidth; 
int lfEscapement ; 
int 1fOrientation; 
int lfWeight; 
BYTE IlfItalic; 
BYTE 1lfUnderline; 
BYTE 1fStrikeOut; 
BYTE lfCharSet; 
BYTE 1lfOutPrecision; 
BYTE 1fClipPrecision; 
BYTE lfQuality; 
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BYTE 1lfFaceName[LF_FACESIZE]; 
} LOGFONT; 


Initializes a CFont object with the characteristics given in a LOGFONT structure 
pointed to by lpLogFont. The font can subsequently be selected as the current font 
for any device. 


This font has the characteristics specified in the LOGFONT structure. When the 
font is selected by using the CDC::SelectObject or CMetaFileDC::SelectObject 
functions, GDI’s font mapper attempts to match the logical font with an existing 
physical font. If it fails to find an exact match for the logical font, it provides an al- 
ternative whose characteristics match as many of the requested characteristics as 
possible. 


TRUE if successful; otherwise FALSE. 


CFont::CreateFont, CDC::SelectObject, CMetaFileDC::SelectObject, 
::CreateFontindirect 


Syntax 


Parameters 


Remarks 


Return Value 
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CFont::FromHandle 


static CFont* FromHandle( HFONT /Font ); 


hFont 
An HFONT handle to a Windows font. 


Returns a pointer to a CFont object when given an HFONT handle to a Windows 
GDI font object. If a CFont object is not already attached to the handle, a tem- 
porary CF ont object is created and attached. This temporary CF ont object is valid 
only until the next time the application has idle time in its event loop, at which 
time all temporary graphic objects are deleted. Another way of saying this is that 
the temporary object is only valid during the processing of one window message. 


A pointer to a CFont object if successful; otherwise NULL. 
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CFrameWnd 


class CFrameWnd : public CWnd 


See Also 


Public Members 


The CFrameWnd class provides the functionality of a 
Windows (SDI) overlapped or pop-up frame window. 


To create a useful frame window for your application, 
derive a class from CFrameWnd. Add member varia- 
bles to the derived class to store data specific to your 
application. Implement message-handler member func- 
tions and a message map in the derived class to specify what happens when mes- 
Sages are directed to the window. 
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You create a frame window in two steps. First, call the constructor CFrameWnd 
to construct the CFrameWnd object, then call the Create member function to cre- 
ate the frame window and attach it to the CFrameWnd object. 


Construction can be a one-step process in a derived class. Write a constructor for 
the derived class and call Create from within the constructor. 


When the user terminates your frame window, destroy the CFrameWnd object or 
call the DestroyWindow member function, which CFrameWnd inherits from 
class CWnd, to remove the window and destroy its data structures. If you allocate 
any memory wi the CFrameWnhd objeci, override the CFrameWhnd destructor to 
dispose of the allocations. 


CWnd, CMDIFrameWnd, CMDIChildWnd 


Data Members 


rectDefault Pass this static CRect as a parameter when creat- 
ing a CFrameWnd object to allow Windows to 
choose the window’s size and position. 


Construction/Destruction 
CFrameWnd Constructs a CFrameWnd object. 


~CFrameWnd Destroys a CFrameWnd object and the frame win- 
dow, frees the accelerator table, and posts an appli- 
cation quit message. 


Initialization 
Create 


LoadAccelTable 


Operations 
GetChildFrame 


GetParentFrame 


Protected Members 
m_hAccelTable 
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Creates and initializes the Windows frame window 
associated with the CFrameWnd object. 


Loads an accelerator table. 


An overridable member function that simply re- 
turns this. A derived class should provide this func- 
tion for access to the active child. 


An overridable member function that simply re- 
turns this. A derived class should provide this func- 
tion for access to the parent frame. 


Contains the command accelerator table for this 
frame window. 
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Member Functions 
CFrameWnd::CFrameWnd 
Syntax CFrameWnd(); 
Remarks Constructs a CFrameWnd object. The frame window is not created until the 


Create member function is called. 


See Also CFrameWnd::Create, CFrameWnd::~CFrameWnd 


CFrameWhnd::~CFrameWnd 


syntax virtual ~CFrameWnd(); 


Remarks Destroys a CFrameWnd object and the frame window, frees the accelerator table 
if loaded, and posts a WM_ QUIT message to terminate the application. 


See Also CFrameWnd::Create, CFrameWnd::CFrameWnd 


CFrameWnd::Create 


Syntax BOOL Create( const char FAR* /[pClassName, 
const char FAR* /pWindowName, 
DWORD dwStyle = WS_OVERLAPPEDWINDOW, 
const RECT S& rect = rectDefault, const CWnd* pParentWnd = NULL, 
const char FAR* /pMenuName = NULL ); 


Parameters [pClassName 
Points to a null-terminated character string that names the Windows class (a 
WNDCLASS struct). The class name can be any name registered with the 
afxRegisterWndClass function or any of the predefined control-class names. 
If NULL, uses the predefined default CFrameWnd attributes. 


Remarks 


Return Value 


See Also 


syntax 


Remarks 


Return Value 


See Also 
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lpWindowName 
Points to a null-terminated character string that represents the window name. 
Used as text for the title bar. 


dwStyle 
Specifies the window style attributes. See the CreateEx member function in the 
CWnd class for a full list of window styles. 


rect 
Specifies the size and position of the window. The rectDefault value allows 
Windows to specify the size and position of the new CFrameWnd object. 


pParentWnd 
Specifies the parent window of this frame window. This parameter should be 
NULL for top-level frame windows. 


lpMenuName 
Identifies the name of the menu resource to be used with the window. Use 
MAKEINTRESOURCKE if the menu has an integer ID instead of a string. 
This parameter can be NULL. 
Construct a CFrameWnd object in two steps. First invoke the constructor, which 
constructs the CFrameWhnd object, then call Create, which creates the Windows 
frame window and attaches it to the CFrameWnd object. Create initializes the 
window’s class name and window name and registers default values for its style, 
parent, and associated menu. 
TRUE if initialization is successful; otherwise FALSE. 


CFrameWnd::CFrameWnd, CFrameWnd::~CFrameWnd, CWnd::CreateEx 


CFrameWnd::GetChildFrame 


virtual CFrameWnd* GetChildFrame(); 


An overridable member function that simply returns this. A derived class should 
override this function to provide access to the active child. 


Returns this. 


CMDIFrameWnd::GetChildFrame 
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Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks | 


Return Value 


See Also 


CFrameWnd::GetParentFrame 
virtual CFrameWnd* GetParentFrame(); 


An overridable member function that simply returns this. A derived class should 
override this function to provide access to the parent frame. 


Returns this. 


CMDIChildWnd::GetParentFrame 


CFrameWnd::LoadAccelTable 


BOOL LoadAccelTable( const char FAR* [pAccelTableName ); 


lpAccelTableName 
Identifies the name of the accelerator resource. Use MAKEINTRESOURCE 
if the resource is identified with an integer ID. 


Loads the specified accelerator table. The member function stores the table handle 
in m_hAccelTable. Only one table may be loaded at a time. 


TRUE if the accelerator table was successfully loaded; otherwise FALSE. 


::LoadAccelerators 
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Data Members 


CFrameWnd::m_hAcceltTable 


Remarks A protected variable of type HANDLE, this data member specifies the command 
accelerator table for the frame window. If the frame window doesn’t have an accel- 
erator table, this data member’s value is NULL. The default 
PreTranslateMessage function uses the accelerator table to translate the appro- 
priate keys into commands. 


CFrameWnd::rectDefault 


Remarks Pass this static CRect as a parameter when creating a window to allow Windows 
to choose the window’s size and position. 


See Also CW_USEDEFAULT 
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class CGdiObject : public CObject 


The CGdiObject class provides a base class for 
various kinds of Windows graphical design interface 
(GDI) objects such as bitmaps, regions, brushes, 
pens, palettes, and fonts. You never create a 
CGdiObject directly. Rather, you create an object from one of its derived classes, 
such as CPen or CBrush. 


See Also CBitmap, CBrush, CFont, CPalette, CPen, CRgn 


Public Members 


Data Members 


m_hObject A HANDLE containing the HBITMAP, 
HPALETTE, HRGN, HBRUSH, HPEN, or 
HFONT attached to this object. 


Construction/Destruction 


CGdiObject Constructs a CGdiObject object. 

~CGdiObject Destroys a CGdiObject object. 

Operations 

GetSafeHandle Returns m_hObject unless this is NULL, in 
which case NULL is returned. 

FromHandle Returns a pointer to a CGdiObject object given a 
handle to a Windows GDI object. 

Attach Attaches a Windows GDI object to a CGdiObject 

| object. 

Detach Detaches a Windows GDI object from a 
CGdiObject object and returns a handle to the 
Windows GDI object. 

DeleteObject Deletes the Windows GDI object attached to the 


CGdiObject object from memory by freeing all 
system storage associated with the object. 


DeleteTempMap Deletes any temporary CGdiObject objects 
created by FromHandle. 


GetObject 
CreateStockObject 


UnrealizeObject 
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Fills a buffer with data that describes the Windows 
GDI object attached to the CGdiObject object. 


Retrieves a handle to one of the Windows pre- 
defined stock pens, brushes, or fonts. 


Resets the origin of a brush or resets a logical 
palette. 
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Member Functions 


Syntax 


Parameters 


Remarks 
Return Value 


See Also 


Syntax 


Remarks 


See Also 


CGdiObject::Attach 


BOOL Attach( HANDLE hObject ); 


hObject 
A HANDLE to a Windows GDI object (for example, HPEN or HBRUSH). 


Attaches a Windows GDI object to a CGdiObject object. 
TRUE if attachment is successful; otherwise FALSE. 


CGdiObject::Detach 


CGdiObject::CGdiObject 
CGdiObject(); 


Constructs a CGdiObject object. You never create a CGdiObject directly. 
Rather, you create an object from one of its derived classes, such as CPen or 
CBrush. 


CPen, CBrush, CFont, CBitmap, CRgn, CPalette 
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CGdiObject::~CGdiObject 


Syntax virtual ~CGdiObject(); 

Remarks Destructor for the CGdiObject class. Calls DeleteObject to delete the attached 
Windows GDI object and then deallocates the CGdiObject object. If you don’t 
want to delete the attached Windows GDI object when deleting a CGdiObject ob- 
ject, call Detach before deleting the CGdiObject object. 

See Also CGdiObject::Detach, CGdiObject::DeleteObject 
CGdiObject::CreateStockObject 

Syntax BOOL CreateStockObject( int n/ndex ); 

Parameters nIndex 


A constant specifying the type of stock object desired. It can be one of the fol- 


lowing values: 


Value Meaning 
BLACK_BRUSH Black brush. 
DKGRAY_BRUSH Dark gray brush. 
GRAY_ BRUSH Gray brush. 
HOLLOW_BRUSH Hollow brush. 
LTGRAY_BRUSH Light gray brush. 
NULL_ BRUSH Null brush. 
WHITE_BRUSH White brush. 
BLACK_PEN Black pen. 
NULL_PEN Null pen. 
WHITE_ PEN White pen. 
ANSL_FIXED_FONT ANSI fixed system font. 


ANSI VAR_ FONT 
DEVICE_DEFAULT_FONT 


ANSI variable system font. 


Device-dependent font. 
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Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Value Meaning 
OEM_ FIXED_FONT OEM-dependent fixed font. 
SYSTEM_ FONT The system font. By default, Windows 


uses the system font to draw menus, 
dialog-box controls, and other text. In 
Windows versions 3.0 and later, the 
system font is proportional width; 
earlier versions of Windows use a 
fixed-width system font. 


SYSTEM_ FIXED_FONT The fixed-width system font used in 
Windows prior to version 3.0. This 
object is available for compatibility 
with earlier versions of Windows. 


DEFAULT_ PALETTE Default color palette. This palette 
consists of the 20 static colors in the 
system palette. 


Retrieves a handle to one of the predefined stock Windows GDI pens, brushes, or 
fonts, and attaches the GDI object to the CGDIObject object. Call this function 
with one of the derived classes that corresponds to the Windows GDI one: type, 
such as CPen for a stock pen. 


Returns TRUE if the function is successful; otherwise FALSE. 


CPen::CPen, CBrush::CBrush, CFont::CFont, CPalette::C Palette 


CGdiObject::DeleteObject 


void DeleteObject(); 


Deletes the attached Windows GDI object from memory by freeing all system 
storage associated with the Windows GDI object. The storage associated with the 
C++ CGdiObject object is not affected by this call. An application should not call 
DeleteObject on a CGdiObject object that is currently selected into a device 
context. 
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When a pattern brush is deleted, the bitmap associated with the brush is not de- 
leted. The bitmap must be deleted independently. 


See Also CGdiObject::Detach 


CGdiObject::DeletefempMap 


Syntax static void DeleteTempMap(); 


Remarks Called automatically by the CWinApp idle time handler, DeleteTempMap 
deletes any temporary CGdiObject objects created by FromHandle. 
Delete TempMap detaches the Windows GDI object attached to a temporary 
CGdiObject object before deleting the CGdiObject object. 


See Also CGdiObject::Detach, CGdiObject::FromHandle 


CGdiObject::Detach 


Syntax HANDLE Detach(); 


Remarks Detaches a Windows GDI object from a CGdiObject object and returns a handle 
to the Windows GDI object. 


Return Value A HANDLE to the Windows GDI object detached, or NULL if no GDI object is 
attached. 


See Also CGdiObject::Attach 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


CGdiObject::FromHandle 


static CGdiObject* FromHandle( HANDLE hObject ); 


hObject 
A HANDLE to a Windows GDI object. 


Returns a pointer to a CGdiObject object given a handle to a Windows GDI ob- 
ject. If a CGdiObject object is not already attached to the Windows GDI object, a 
temporary CGdiObject object is created and attached. 


This temporary CGdiObject object is only valid until the next time the applica- 
tion has idle time in its event loop, at which time all temporary graphic objects are 
deleted. Another way of saying this is that the temporary object is only valid 
during the processing of one window message. 


A pointer to a CGdiObject that may be temporary or permanent. 


CGdiObject::DeleteTempMap 


CGdiObject::GetObject 


int GetObject( int nCount, LPSTR [pObject ) const; 


nCount 

Specifies the number of bytes to copy into the /pObject buffer. 
lpObject 

Points to a user-supplied buffer that is to receive the information. 


Fills a buffer with data that defines a specified object. The function retrieves a 
data structure whose type depends on the type of graphic object, as shown by the 
following list: 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 
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Object Buffer type 
CPen LOGPEN 
CBrush LOGBRUSH 
CFont LOGFONT 


CBitmap BITMAP 
CPalette int 
CRegn Not supported 


If the object is a CBitmap object, GetObject returns only the width, height, and 
color format information of the bitmap. The actual bits can be retrieved by using 
CBitmap::GetBitmapBits. 

If the object is a CPalette object, GetObject retrieves an integer that specifies the 
number of entries in the palette. The function does not retrieve the 


LOGPALETTE structure that defines the palette. An application can get informa- 
tion on palette entries by calling CPalette::GetPaletteEntries. 


The number of bytes retrieved, or 0 if an error occurs. 


CBitmap::GetBitmapBits, CPalette::GetPaletteEntries 


CGdiObject::GetSafeHandle 


HANDLE GetSafeHandle() const; 


Returns m_hObject unless this is NULL, in which case NULL is returned. This 
is part of the general handle interface paradigm and is useful when NULL is a 
valid or special value for a handle. 


A HANDLE to the attached Windows GDI object, or NULL if no object is 
attached. 
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Syntax 


Remarks 


Return Value 


See Also 


CGdiObject::UnrealizeObject 


BOOL UnrealizeObject(); 


Resets the origin of a brush or resets a logical palette. While UnrealizeObject is a 
member function of the CGdiObject class, it should be invoked only on CBrush 
or CPalette objects. 


For CBrush objects, UnrealizeObject directs the system to reset the origin of the 
given brush the next time it is selected into a device context. If the object is a 
CPalette object, UnrealizeObject directs the system to realize the palette as 
though it had not previously been realized. The next time the application calls the 
CDC::RealizePalette function for the specified palette, the system completely re- 
maps the logical palette to the system palette. 


The UnrealizeObject function should not be used with stock objects. The 
UnrealizeObject function must be called whenever a new brush origin is set (by 
means of the CDC::SetBrushOrg function). The UnrealizeObject function must 
not be called for the currently selected brush or currently selected palette of any 
display context. 


TRUE if successful; otherwise FALSE. 


CDC::RealizePalette, CDC::SetBrushOrg 


CGdiObject::m_hObject 


Data Members 


Remarks 


CGdiObject::m_ hObject 


A HANDLE containing the HBITMAP, HRGN, HBRUSH, HPEN, 
HPALETTE, or HFONT attached to this object. 
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CListBox 


class CListBox : public CWnd 


The CListBox class provides the functionality of a 
Windows list box. A list box displays a list of items, 
such as filenames, that the user can view and select. 


In a single-selection list box, the user can only select 
one item. In a multiple-selection list box, a range of 
items can be selected. When the user selects an item, it 
is highlighted and the list box sends a notification message to the parent window. 


The list box itself automatically displays horizontal or vertical scroll bars if the list 
within the box is too large for the list-box window. 


You create a list-box control in two steps. First, call the constructor CListBox to 
construct the CListBox object, then call the Create member function to create the 
Windows list-box control and attach it to the CListBox object. 


Construction can be a one-step process in a class derived from CListBox. Write a 
constructor for the derived class and call Create from within the constructor. 


If you want to handle the Windows notification messages sent by a CListBox ob- 
ject to its parent (usually a class derived from CDialog or CModalDialog), add 
the appropriate message-map entries and message-handler member functions to 
the parent class to handle the messages you want to process. Potential message- 
map entries are: 


ON_COMMAND 
ON_LBN_DBLCLK 
ON_LBN_ERRSPACE 
ON_LBN_KILLFOCUS 
ON_LBN_SELCHANGE 
ON_LBN_SETFOCUS 


If you create a CListBox object within a dialog box (through a dialog resource), 
the CListBox is automatically destroyed when the user closes the dialog box. 


If you create a CListBox object within a window, you may also need to destroy it. 
If you create the CListBox object on the stack, it is destroyed automatically. If 
you create the CListBox object on the heap by using the new function, you must 
call delete on the object to destroy it when the user terminates the Windows list 
box. 


If you allocate any memory in the CListBox object, override the CListBox 
destructor to dispose of the allocations. 


See Also 


Public Members 
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CWnd, CButton, CComboBox, CEdit, CScrollBar, CStatic, CModalDialog, 


CDialog 


Construction/Destruction 
CListBox 


Initialization 
Create 


General Operations 
GetCount 
GetHorizontalExtent 


SetHorizontalExtent 
GetTopIndex 
SetTopIndex 
GetItemData 
SetItemData 
GetItemRect 


GetSel 

GetText 
GetTextLen 
SetColumn Width 
SetTabStops 


Constructs a CListBox object. 


Creates the Windows list box and attaches it to the 
CListBox object. 


Returns the number of strings in a list box. 


Returns the width in pixels that a list box can be 
scrolled horizontally. 


Sets the width in pixels that a list box can be 
scrolled horizontally. 


Returns the index of the first visible string in a list 
box. 


Sets the zero-based index of the first visible string 
in a list box. 


Returns the 32-bit value associated with the list- 
box item. 


Sets the 32-bit value associated with the list-box 
item. 


Returns the bounding rectangle of the list-box item 
as itis currently displayed. 


Returns the selection state of a list-box item. 
Copies a list-box item into a buffer. 

Returns the length in bytes of a list-box item. 
Sets the column width of a multicolumn list box. 


Sets the tab-stop positions in a list box. 
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CListBox 


Single Selection Operations 


GetCurSel 


SetCurSel 


Returns the zero-based index of the currently 
selected string in a list box. 


Selects a list-box string. 


Multiple Selection Operations 


SetSel 
GetSelCount 
GetSelltems 


SelltemRange 


String Operations 
AddString 
DeleteString 
InsertString 
ResetContent 

Dir 


FindString 
SelectString 


Selects or deselects a list box item in a multiple- 
selection list box. 


Returns the number of strings currently selected in 
a multiple-selection list box. 


Returns the indices of the strings currently selected 
in a list box. 


Selects or deselects a range of strings in a multiple- 
selection list box. 


Adds a string to a list box. 

Deletes a string from a list box. 

Inserts a string at a specific location in a list box. 
Clears all the entries from a list box. 


Adds filenames from the current directory to a 
list box. 


Searches for a string in a list box. 


Searches for and selects a string in a single- 
selection list box. 
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Member Functions 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


CListBox::AddString 


int AddString( const char FAR* Ip/tem ); 


lpltem 
Points to the null-terminated string that is to be added. 


Adds a string to a list box. If the list box was not created with the LBS_SORT 
style, the string is added to the end of the list. Otherwise, the string is inserted into 
the list, and the list is sorted. 


Use InsertString to insert a string into a specific location within the list box. 


The zero-based index to the string in the list box. The return value is LB_ERR if 
an error occurs; the return value is LBL ERRSPACE if insufficient space is avail- 
able to store the new string. 


CListBox::InsertString, LB_ADDSTRING 


CListBox::CListBox 


CListBox(); 


You construct a CListBox object in two steps. First call the constructor CListBox, 
then call Create, which initializes the Windows list box and attaches it to the 
CListBox. 


CListBox::Create 
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Syntax 


Parameters 


Remarks 


CListBox::Create 


BOOL Create( DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, 
UINT n/ID ); 


dwStyle 
Specifies the style of the list box. 


rect 
Specifies the list-box size and position. Can be either a CRect object or a 
RECT structure. 


pParentWnd 
Specifies the list box’s parent window (usually a CDialog or CModalDialog 
object). It must not be NULL. 


nID 
Specifies the list box’s resource ID. 


You construct a CListBox object in two steps. First call the constructor, then call 
Create, which initializes the Windows list box and attaches it to the CListBox 
object. 


When Create executes, Windows sends the WM_NCCREATE, 
WM_CREATE, WM_NCCALCSIZE, and WM_GETMINMAXINFO 
messages to the list-box control. 


These messages are handled by default by the OnNcCreate, OnCreate, 
OnNcCalcSize, and OnGetMinMaxInfo member functions in the CWnd base 
class. To extend the default message handling, derive a class from CListBox, add 
a message map to the new class, and override the preceding message-handler mem- 
ber functions. Override OnCreate, for example, to perform needed initialization 
for a new class. 


To handle Windows notification messages sent from a CListBox object to its 
parent, add any of the following message-map entries that you want to process to 
the parent class message map: 


ON_ COMMAND 
ON_LBN_DBLCLK 
ON_LBN_ERRSPACE 
ON_LBN_KILLFOCUS 
ON_LBN_SELCHANGE 
ON_LBN_SETFOCUS 


Apply the following window styles to a list-box control: 


Style 

WS_ CHILD 
WS_ VISIBLE 
WS_ DISABLED 
WS_VSCROLL 
WS_HSCROLL 
WS_GROUP 
WS_TABSTOP 
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Application 

Always. 

Usually. 

Rarely. 

Adds a vertical scroll bar. 
Adds a horizontal scroll bar. 
To group controls. 


To allow tabbing to this control. 


See CreateEx in the CWnd base class for a full description of these window 


styles. 


Use any combination of the following list-box styles for dwStyle: 


Style 
LBS_EXTENDEDSEL 


LBS_HASSTRINGS 


LBS_MULTICOLUMN 
LBS_MULTIPLESEL 


LBS_NOINTEGRALHEIGHT 


Meaning 


The user can select multiple items 
using the SHIFT key and the mouse or 
special key combinations. 


Specifies an owner-draw list box that 
contains items consisting of strings. 
The list box maintains the memory 
and pointers for the strings so the 
application can use the GetText 
member function to retrieve the text 
for a particular item. 


Specifies a multicolumn list box that 
is scrolled horizontally. The 
SetColumn Width member function 
sets the width of the columns. 


String selection is toggled each time 
the user clicks or double-clicks the 
string. Any number of strings can be 
selected. 


The size of the list box is exactly the 
size specified by the application when 
it created the list box. Usually, 
Windows sizes a list box so that the 
list box does not display partial items. 
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Style 
LBS_NOREDRAW 


LBS_ NOTIFY 


LBS_OWNERDRAWFIXED 


LBS_OWNERDRAW VARIABLE 


LBS_SORT 


LBS_STANDARD 


LBS_USETABSTOPS 


Meaning 


List-box display is not updated when 
changes are made. This style can be 
changed at any time by sending a 
WM_SETREDRAW message. 


Parent window receives an input 
message whenever the user clicks or 
double-clicks a string. 


The owner of the list box is 
responsible for drawing its contents; 
the items in the list box are the same 
height. 


The owner of the list box is 
responsible for drawing its contents; 
the items in the list box are variable 
in height. 


Strings in the list box are sorted 
alphabetically. 


Strings in the list box are sorted 
alphabetically, and the parent window 
receives an input message whenever 
the user clicks or double-clicks a 
string. The list box contains borders 
on all sides. 


Allows a list box to recognize and 
expand tab characters when drawing 
its strings. The default tab positions 
are 32 dialog units. (A dialog unit is a 
horizontal or vertical distance. One 
horizontal dialog unit is equal to one- 
fourth of the current dialog base 
width unit. The dialog base units are 
computed based on the height and 
width of the current system font. The 


_ GetDialogBaseUnits Windows 


function returns the current dialog 
base units in pixels.) | 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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Style Meaning 


LBS_WANTKEYBOARDINPUT The owner of the list box receives 
WM_VKEYTOITEM or 
WM_CHARTOITEM messages 
whenever the user presses a key when 
the list box has input focus. This 
allows an application to perform 
special processing on the keyboard 
input. 


TRUE if successful; otherwise FALSE. 


CListBox::CListBox 


CListBox::DeleteString 


int DeleteString( UINT nindex ); 


nIndex 
Specifies the zero-based index of the string to be deleted. 


Deletes an item in a list box. 


A count of the strings remaining in the list. The return value is LB_ ERR if the 
nIndex specifies an index greater then the number of items in the list. 


LB_DELETESTRING, CListBox::AddString, CListBox::InsertString 
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CListBox::Dir 
Syntax int Dir( UINT attr, const char FAR* [pWildCard ); 
Parameters attr 


Can be any combination of the CFile::GetStatus enum flags, or any combina- 
tion of the following values: 


Value Meaning 
Ox0000 File can be read from or written to. 
Ox0001 File can be read from, but not written to. 
0x0002 File is hidden and does not appear in a directory listing. 
Ox0004 File is a system file. 
0x0010 The name specified by lpWildCard specifies a directory. 
0x0020 File has been archived. 
0x4000 Include all drives that match the name specified by 
lp WildCard. 
Ox8000 Exclusive flag. If the exclusive flag is set, only files of the 


specified type are listed. Otherwise, files of the specified type 
are listed in addition to “normal” files. 


lp WildCard 
Points to a file-specification string. The string can contain wildcards (for 
example, *.*). 


Remarks Adds a list of filenames and/or drives to a list box. 


Return Value The zero-based index of the last filename added to the list. The return value is 
LB_ERR if an error occurs; the return value is LB_ERRSPACE if insufficient 
space is available to store the new strings. 


See Also CWnd::DlgDirList, LB_ DIR, CFile::GetStatus 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


CListBox::GetCount 361 


CListBox::FindString 


int FindString( int nStartAfter, const char FAR* [p/tem ) const; 


nStartAfter 
Contains the zero-based index of the item before the first item to be searched. 
When the search reaches the bottom of the list box, it continues from the top of 
the list box back to the item specified by nStartAfter. If nStartAfter is —1, the 
entire list box is searched from the beginning. 


[pltem 
Points to the null-terminated string that contains the prefix to search for. The 
search is case-independent, so this string may contain any combination of 
uppercase and lowercase letters. 


Finds the first string in a list box that contains the specified prefix without chang- 
ing the list-box selection. Use the SelectString member function to both find and 
select a string. 


The zero-based index of the matching item, or LB_ ERR if the search was 
unsuccessful. 


CListBox::SelectString, CListBox::AddString, CListBox::InsertString, 
LB_FINDSTRING 


CListBox::GetCount 


int GetCount() const; 


Retrieves the number of items in a list box. 


The returned count is one greater then the index value of the last item (the index is 
zero-based). 


The number of items in the list box, or LB_ ERR if an error occurs. 


LB_GETCOUNT 
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Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


CListBox::GetCurSel 


int GetCurSel() const; 


Retrieves the zero-based index of the currently selected item, if any, in a single- 
selection list box. 


GetCurSel should not be called for a multiple-selection list box. 


The zero-based index of the currently selected item. It is LB_ ERR if no item is 
currently selected or if the list box is a multiple-selection list box. 


LB_GETCURSEL, CListBox::SetCurSel 


CListBox::GetHorizontalExtent 


int GetHorizontalExtent() const; 


Retrieves from a list box the width in pixels by which the list box can be scrolled 
horizontally if the list box has horizontal scroll bars. 


To respond to GetHorizontalExtent, the list box must have been defined with the 
WS_HSCROLL style. 


The scrollable width of the list box, in pixels. 


CListBox::SetHorizontalExtent, LB_GETHORIZONTALEXTENT | 
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CListBox::GetltemData 


Syntax DWORD GetItemData( int n/ndex ) const; 


Parameters nIndex 
Specifies the zero-based index of the item in the list box. 


Remarks Retrieves the application-supplied 32-bit value associated with the specified list- 
box item. 


The 32-bit value was the /p/tem parameter of a SetItemData call. 
Return Value The 32-bit value associated with the item, or LB_ ERR if an error occurs. 


See Also CListBox::AddString, CListBox::InsertString, CListBox::SetItemData, 
LB_GETITEMDATA 


CListBox::GetiltemRect 


Syntax int GetItemRect( int n/Index, LPRECT /pRect ) const; 


Parameters nIndex 
Specifies the zero-based index of the item. 


[pRect 
Specifies a long pointer to a RECT data structure that receives the list-box 
client coordinates of the item. 


Remarks Retrieves the dimensions of the rectangle that bounds a list-box item as it 1s cur- 
rently displayed in the list-box window. 


Return Value LB_ERR if an error occurs. 


See Also LB_GETITEMRECT 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 
Remarks 


Return Value 


See Also 


Syntax 


Parameters 


CListBox::GetSel 


int GetSel( int n/ndex ) const; 


nIndex 
Specifies the zero-based index of the item. 


Retrieves the selection state of an item. This member function works with both 
single and multiple-selection list boxes. 


A positive number if the specified item is selected; otherwise, it is 0. The return 
value is LB_ ERR if an error occurs. 


LB_GETSEL, CListBox::SetSel 


CListBox::GetSelCount 


int GetSelCount() const; 
Retrieves the total number of selected items in a multiple-selection list box. 


The count of selected items in a list box. If the list box is a single-selection list 
box, the return value is LB_ERR. 


CListBox::SetSel, LB_GETSELCOUNT 


CListBox::GetSel Items 


int GetSelltems( int nMaxItems, LPINT rglndex ) const; 


nMaxlitems 
Specifies the maximum number of selected items whose item numbers are to be 
placed in the buffer. 


rglndex 
Specifies a long pointer to a buffer large enough for the number of integers 
specified by nMaxItems. : 


CListBox::GetText 365 


Remarks Fills a buffer with an array of integers that specifies the item numbers of selected 
items in a multiple-selection list box. 


Return Value The actual number of items placed in the buffer. If the list box is a single-selection 
list box, the return value is LB_ ERR. 


See Also LB_GETSELITEMS 


CListBox::GetText 


Syntax int GetText( int n/ndex, char FAR* [pBuffer ) const; 


void GetText( int n/ndex, CString& rString ) const; 


Parameters nIndex 
Specifies the zero-based index of the string to be retrieved. 
lpBuffer 
Points to the buffer that receives the string. The buffer must have sufficient 
space for the string and a terminating null character. The size of the string can 
be determined ahead of time by calling the GetTextLen member function. 


rString 
A reference to a CString object. 


Remarks Gets a string from a list box. The second form of this member function fills a 
CString object with the string text. 


Return Value The length (in bytes) of the string, excluding the terminating null character. If 
nIndex does not specify a valid index, the return value is LB_ERR. 


See Also CListBox::GetTextLen, LB_GETTEXT 
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CListBox::GetTextLen 


Syntax int GetTextLen( int n/ndex ) const; 


Parameters nIndex 
Specifies the zero-based index of the string. 


Remarks Gets the length of a string in a list box item. 


Return Value The length of the string in bytes, excluding the terminating null character. If 
nIndex does not specify a valid index, the return value is LB_ERR. 


See Also CListBox::GetText, LB_GETTEXTLEN 


CListBox::GetTopIndex 


Syntax int GetTopIndex() const; 

Remarks Retrieves the zero-based index of the first visible item in a list box. Initially, item 
O is at the top of the list box, but if the list box is scrolled, another item may be at 
the top. 

Return Value The zero-based index of the first visible item in a list box. 

See Also CListBox::SetTopIndex, LB_GETTOPINDEX 


CListBox::InsertString 


Syntax int InsertString( int n/ndex, const char FAR* /pitem ); 


Parameters nIndex 
Specifies the zero-based index of the position to insert the string. If this parame- 
ter is —1, the string is added to the end of the list. 


lpItem 
Points to the null-terminated string that is to be inserted. 


Remarks 


Return Value 


See Also 


CListBox::SelectString 367 
Inserts a string into the list box. Unlike the AddString member function, 
InsertString does not cause a list with the LBS_SORT style to be sorted. 
The zero-based index of the position at which the string was inserted. The return 
value is LB_ ERR if an error occurs; the return value is LB_ERRSPACE if in- 


sufficient space is available to store the new string. 


CListBox::AddString, LB_INSERTSTRING 


Syntax 
Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CListBox::ResetContent 


void ResetContent(); 
Removes all items from a list box. 


LB_RESETCONTENT 


CListBox::SelectString 


int SelectString( int nStartAfter, const char FAR* [pltem ); 


nStartAfter 
Contains the zero-based index of the item before the first item to be searched. 
When the search reaches the bottom of the list box, it continues from the top of 
the list box back to the item specified by nStartAfter. If nStartAfter is —1, the en- 
tire list box is searched from the beginning. 


lpltem 
Points to the null-terminated string that contains the prefix to search for. The 
search is case-independent, so this string may contain any combination of up- 
percase and lowercase letters. 


Searches for a list-box item that matches the specified string, and if a matching 
item is found, it selects the item. 


The list box is scrolled, if necessary, to bring the selected item into view. 
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This member function cannot be used with a list box that has the 
LBS_MULTIPLESEL style. 


An item is selected only if its initial characters (from the starting point) match the 
characters in the string specified by /p/tem. 


Use the FindString member function to find a string without selecting the item. 


Return Value The index of the selected item if the search was successful. If the search was un- 
successful, the return value is LB_ ERR and the current selection is not changed. 


See Also CListBox::FindString, LB_SELECTSTRING 


CListBox::SelltemRange 


Syntax int SelItemRange( BOOL bSelect, int nFirstItem, int nLastltem ); 


Parameters bSelect 
Specifies how to set the selection. If bSelect is TRUE, the string is selected and 
highlighted; if FALSE, the highlight is removed and the string is no longer 
selected. 


nfirstltem 
Specifies the zero-based index of the first item to set. 


nLastltem 
Specifies the zero-based index of the last item to set. 


Remarks Selects one or more consecutive items in a multiple-selection list box. 


Use this member function only with multiple-selection list boxes. 
~ Return Value LB_ERR if an error occurs. 


See Also LB_SELITEMRANGE, CListBox::GetSelltems 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CListBox::SetColumnWidth 


void SetColumnWidth( int cxWidth ); 


cxWidth 
Specifies the width in pixels of all columns. 


Sets the width in pixels of all columns in a multicolumn list box (created with the 
LBS_MULTICOLUMN style). 


LB_SETCOLUMNWIDTH 


CListBox::SetCurSel 


int SetCurSel( int nSelect ); 


nSelect 
Specifies the zero-based index of the string to be selected. If nSelect is —1, the 
list box is set to have no selection. 


Selects a string and scrolls it into view, if necessary. When the new string is 
selected, the list box removes the highlight from the previously selected string. 


Use this member function only with single-selection list boxes. It cannot be used 
to set or remove a selection in a multiple-selection list box. 


LB_ERR if an error occurs. 


LB_SETCURSEL, CListBox::GetCurSel 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 
Return Value 


See Also 


CListBox::SetHorizontalExtent 


void SetHorizontalExtent( int cxExtent ); 


cxExtent 
Specifies the number of pixels by which the list box can be scrolled 
horizontally. 


Sets the width, in pixels, by which a list box can be scrolled horizontally. If the 
size of the list box is smaller than this value, the horizontal scroll bar will horizon- 


tally scroll items in the list box. If the list box is as large or larger than this value, 
the horizontal scroll bar is hidden. 


To respond to a call to SetHorizontalExtent, the list box must have been defined 
with the WS_HSCROLL style. 


CListBox::GetHorizontalExtent, LB_SETHORIZONTALEXTENT 


CListBox::SetltemData 


int SetItemData( int nJndex, DWORD dwi/temData ); 


nindex 
Specifies the zero-based index of the item. 


dwlitemData 
Specifies the value to be associated with the item. 


Sets a 32-bit value associated with the specified item in a list box. 
LB_ERR if an error occurs. 


CListBox::GetItemData, LB_SETITEMDATA 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 
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CListBox::SetSel 


int SetSel( int n/ndex, BOOL bSelect = TRUE ); 


nIndex 
Contains the zero-based index of the string to be set. If —1, the selection is 
added to or removed from all strings, depending on the value of bSelect. 


bSelect 
Specifies how to set the selection. If bSelect is TRUE, the string 1s selected and 
highlighted; if FALSE, the highlight is removed and the string is no longer 
selected. The specified string is selected and highlighted by default. 


Selects a string in a multiple-selection list box. 


Use this message only with multiple-selection list boxes. 
LB_ERR if an error occurs. 


CListBox::GetSel, LB_SETSEL 


CListBox::SetlabStops 


BOOL SetTabStops( int nTabStops, LPINT rgTabStops ); 
void SetTabStops(); 
BOOL SetTabStops( int cxEachStop ); 


nTabStops 
Specifies the number of tab stops to have in the list box. 


rgTabStops 
Points to the first member of an array of integers containing the tab-stop posi- 
tions in dialog units. (A dialog unit is a horizontal or vertical distance. One hori- 
zontal dialog unit is equal to one-fourth of the current dialog base width unit, 


372.  GCListBox::SetTopIndex 


and one vertical dialog unit is equal to one-eighth of the current dialog base 
height unit. The dialog base units are computed based on the height and width 
of the current system font. The GetDialogBaseUnits Windows function returns 
the current dialog base units in pixels.) The tab stops must be sorted in increas- 
ing order; back tabs are not allowed. 


cxEachStop 
Tab stops are set at every cxEachStop dialog units. 


Remarks Sets the tab-stop positions in a list box. 


If SetTabStops() is called, nTabStops is 0, rgTabStops is NULL, and the default 
tab stop is 2 dialog units. 


If nTabStops is 1, tab stops will be separated by the distance specified by 
rgTabStops. 


If rgTabStops points to more than a single value, then a tab stop will be set for 
each value in rgTabStops, up to the number specified by nTabStops. 


To respond to a call to the SetTabStops member function, the list box must have 
been created with the LBS_USETABSTORS style. 


Return Value TRUE if all the tabs were set; otherwise FALSE. 


See Also LB_SETTABSTOPS, ::GetDialogBaseUnits 


CListBox::SetTopindex 


Syntax int Set TopIndex( int nJndex ); 


Parameters nIndex 
Specifies the zero-based index of the list-box item. 


Remarks Ensures that a particular list-box item is visible. 


The system scrolls the list box until either the list-box item appears at the top of 
the list box or the maximum scroll range has been reached. 


Return Value LB_ERR if an error occurs. 


See Also CListBox::GetTopIndex, LB_SETTOPINDEX 


CMapPtrToPtr = 373 


class CMapPtrToPtr : public CObject 


Public Members 


The CMapPtrToPtr class supports maps of 
void pointers keyed by void pointers. 


CObject 


The member func tions O f CMapPtrToP tr rr ieeaecrauaaeconsnencsseasseeseen eines meron rere) 
are similar to the member functions of class 

CMapStringToOb. Because of this similarity, you can use the 
CMapStringToOb reference documentation for member function specifics. 
Wherever you see a CObject pointer as a function parameter or return value, sub- 
stitute a pointer to void. Wherever you see a CString or a const pointer to char as 
a function parameter or return value, substitute a pointer to void. 


BOOL CMapStringToOb::Lookup( const char* <key>, CObject*& <rValue> ) 
const; 


for example, translates to 

BOOL CMapPtrToPtr::Lookup( void* <key>, void*& <rValue> ) const; 
CMapPtrToPtr incorporates the IMPLEMENT_DYNAMIC macro to support 
run-time type access and dumping to a CDumpContext object. If you need a 


dump of individual map elements (pointer values), you must set the depth of the 
dump context to 1 or greater. 


Pointer-to-pointer maps may not be serialized. 


When a CMapPtrToPtr object is deleted, or when its elements are removed, only 
the pointers are removed, not the entities they reference. 


#include <afxcoll.h> 


Construction/Destruction 


CMapPtrToPtr Constructs a collection that maps void pointers to 
void pointers. 


~CMapPtrToPtr Destroys a CMapPtrToPtr object. 


CMapPtrToPtr 


Operations 
Lookup 


SetAt 
operator [ | 


RemoveKey 
RemoveAll 
GetStartPosition 
GetNextAssoc 


Status 
GetCount 
IsEmpty 


Looks up a void pointer, based on the void pointer 
key. The pointer value is used for the key compari- 
son, not the entity it points to. 


Inserts an element into the map; replaces an 
existing element if a matching Key is found. 


Inserts an element into the map—operator 
substitution for SetAt. 


Removes an element specified by a key. 
Removes all the elements from this map. 
Returns the position of the first element. 


Gets the next element for iterating. 


Returns the number of elements in this map. 


Tests for the empty-map condition (no elements). 
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class CMapPtrToWord : public CObject 


The CMapPtrToWord class supports maps of 
16-bit words keyed by void pointers. 


The member functions of CMapPtrToWord 
are similar to the member functions of class 
CMapStringToOb. Because of this similarity, you can use the 
CMapStringToOb reference documentation for member function specifics. 
Wherever you see a CObject pointer as a function parameter or return value, sub- 
stitute WORD. Wherever you see a CString or a const pointer to char as a func- 
tion parameter or return value, substitute a pointer to void. 


BOOL CMapStringToOb::Lookup( const char* <key>, CObject*& <rValue> ) 
const; 


for example, translates to 

BOOL CMapPtrToWord::Lookup( const void* <key>, WORD& <rValue> ) const; 
CMapWordToPtr incorporates the IMPLEMENT_DYNAMIC macro to sup- 
port run-time type access and dumping to a CDumpContext object. If you need a 


dump of individual map elements, you must set the depth of the dump context to 1 
or greater. 


Pointer-to-word maps may not be serialized. 


When a CMapPtrToWord object is deleted, or when its elements are removed, 
the pointers and the words are removed. The entities referenced by the key point- 
ers are not removed. 


#include <afxcoll.h> 


Public Members 


Construction/Destruction 


CMapPtrToWord Constructs a collection that maps void pointers to 
16-bit words. 


~CMapPtrToWord Destroys a CMapPtrToWord object. 
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CMapPtrToWord 


Operations 
Lookup 


SetAt 
operator [ | 


RemoveKey 
RemoveAll 
GetStartPosition 
GetNextAssoc 


Status 
GetCount 
IsEmpty 


Returns a WORD, using a void pointer as a key. 
The pointer value is used for the key comparison, 
not the entity it points to. 


Inserts an element into the map; replaces an 
existing element if a matching key is found. 


Inserts an element into the map—operator 
substitution for SetAt. 


Removes an element specified by a key. 
Removes all the elements from this map. 
Returns the position of the first element. 


Gets the next element for iterating. 


Returns the number of elements in this map. 


Tests for the empty-map condition (no elements). 
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class CMapStringToOb : public CObject 


CMapStringToOb is a dictionary collection class 
that maps unique CString objects to CObject point- 
ers. Once you have inserted a CString—CObject* 
pair (element) into the map, you can efficiently re- 
trieve or delete the pair using a string or a CString value as a key. You can also 
iterate over all the elements in the map. 


A variable of type POSITION is used for alternate entry access in all map varia- 
tions. You can use a POSITION to “remember” an entry and to iterate through 
the map. You might think that this iteration is sequential by key value; it is not. 
The sequence of retrieved elements is indeterminate. 


CMapStringToOb incorporates the IMPLEMENT_SERIAL macro to support 
serialization and dumping of its elements. If a map is stored to an archive, either 
with the overloaded insertion operator or with the Serialize member function, 
each element is, in turn, serialized. 


If you need a diagnostic dump of the individual elements in the map (the CString 
value and the CObject contents), you must set the depth of the dump context to 1 
or greater. 


When a CMapStringToOb object is deleted, or when its elements are removed, 
the CString objects and the CObject pointers are removed. The objects refer- 
enced by the CObject pointers are not destroyed. 


#include <afxcoll.h> 


See Also CMapPtrToPtr, CMapPtrToWord, CMapStringToPtr, 
CMapStringToString, CMapWordToOb, CMapWordToPtr 


Derivation Map class derivation is similar to list derivation. See the tutorial in the Microsoft 
Class Library User’s Guide for an illustration of the derivation of a special- 
purpose list class. 
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Public Members 


Construction/Destruction 
CMapStringToOb 


~CMapStringToOb 


Operations 
Lookup 


SetAt 
operator [ | 


RemoveKey 


RemoveAll 


GetStartPosition 
GetNextAssoc 


Status 
GetCount 
IsEmpty 


Constructs a collection that maps CString values 
to CObject pointers. 


Destroys a CMapStringToOb object. 


Returns a CObject pointer, based on a CString 
value. 


Inserts an element into the map; replaces an ex- 
isting element if a matching key is found. 


Inserts an element into the map—operator 
substitution for SetAt. 


Removes an element specified by a Key. 
Removes all the elements from this map. 
Returns the position of the first element. 


Gets the next element for iterating. 


Returns the number of elements in this map. 


Tests for the empty-map condition (no elements). 
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Member Functions 


Syntax 


Parameters 


Remarks 


Example 


Syntax 


Remarks 


CMapString To0b::CMapString foO0b 


CMapStringToOb( int nBlockSize = 10 ); 


nBlockSize 
The memory-allocation granularity for extending the map. 


Constructs an empty CString-to-CObject* map. As the map grows, memory is al- 
located in units of nBlockSize entries. 


See CObList::CObList for a listing of the CAge class used in all collection ex- 
amples. 


CMapStringloOb map(20); // Map on the stack with blocksize of 20 


CMapStringTloOb* pm = new CMapStringlo0Ob; // Map on the heap 
// with default blocksize 


CMapString fo0b::~CMapString ToOb 
~CMapStringToOb(); 


Destroys a CMapStringToOb object, including all CString key objects contained 
in the map, but does not destroy the CObject objects. 
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Syntax 
Return Value 


Example 


See Also 


Syntax 


Parameters 


Remarks 


CMapString ToOb::GetCount 


int GetCount() const; 
The number of elements in this map. 


CMapStringToOb map; 


map.SetAt( "Bart", new CAge( 13 ) ); 
map.SetAt( "Homer", new CAge( 36 ) ); 
ASSERT( map.GetCount() == 2 ); 


CMapStringToOb:: IsEmpty 


CMapStringToOb::GetNextAssoc 


void GetNextAssoc( POSITION& rNextPosition, CString& rKey, 
CObject*& rValue ) const; 


rNextPosition 
A reference to a POSITION value returned by a previous GetNextAssoc or 
GetStartPosition call. 


rKey 
The returned key of the retrieved element (a string). 


rValue 
The returned value of the retrieved element (a CObject pointer). 


Retrieves the map element at rNextPosition, then updates rNextPosition to refer to 
the next element in the map. This function is most useful for iterating through all 
the elements in the map. Note that the position sequence is not necessarily the 
Same as the key value sequence. 


If the retrieved element is the last in the map, then the new value of rNextPosition 
is set to NULL. 
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Example CMapStringToOb map; 
POSITION pos; 
CString key; 
CAge* pa; 


map.SetAt( "Bart", new CAge( 13 ) ); 
map.SetAt( "Lisa", new CAge( 11 ) ); 
map.SetAt( "Homer", new CAge( 36 ) ); 
map.SetAt( "Marge", new CAge( 35 ) ); 
// iterate through the entire map, dumping both name and age 
for( pos = map.GetStartPosition(); pos != NULL; ) 
{ 
map.GetNextAssoc( pos, key, pa ); 
#Hifdef _DEBUG 
afxDump << key << ": " << pa << “\\n"; 
fendi f 
i; 


The results from this program are as follows: 


Lisa : a CAge at $4724 11 
Marge : a CAge at $47A8 35 
Homer : a CAge at $4766 36 
Bart : a CAge at $45D4 13 


See Also CMapStringToOb::GetStartPosition 


CMapString foOb::GetStartPosition 


Syntax POSITION GetStartPosition( const; 


Remarks Starts a map iteration by returning a POSITION value that can be passed to a 
GetNextAssoc call. The iteration sequence is not predictable; therefore the “first 
element in the map” has no special significance. 


Example See the example for the function GetNextAssoc. 
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Syntax 
Return Value 
Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


CMapString foOb::lsEmpty 

BOOL IsEmpty( const; 

TRUE if this map contains no elements; otherwise FALSE. 
See the example for RemoveAll. 


CMapStringToOb::GetCount 


CMapString ToOb::Lookup 


BOOL Lookup( const char* key, CObject*& rValue ) const; 


key 
The string key that identifies the element to be looked up. 


rValue 
The returned value from the looked-up element. 


Lookup uses a hashing algorithm to quickly find the map element with a key that 
matches exactly (CString value). 


TRUE if the element was found; otherwise FALSE. 


CMapStringToOb map; 
CAge* pa; 


map.SetAt( "Bart", new CAge( 13 ) ); 

map.SetAt( "Lisa", new CAge( 11 ) ); 

map.SetAt( "Homer", new CAge( 36 ) ); 

map.SetAt( "Marge", new CAge( 35 ) ); 

ASSERT( map.Lookup( “Lisa", pa ) ); // Is "Lisa" in the map? 
ASSERT( *pa == CAge( 11 ) ); // Is she 11? 


CMapStringToOb::operator [ | 


Syntax 


Remarks 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


CMapStringfoOb::RemoveKey _383 


CMapSiring fo0b::Removeall 


void RemoveAll(); 


Removes all the elements from this map and destroys the CString key objects. 
The CObject objects referenced by each key are not destroyed. The RemoveAll 
function can cause memory leaks if you do not ensure that the referenced CObject 
objects are destroyed. 


The function works correctly if the map is already empty. 


{ 
CMapStringloOb map; 


CAge agel( 13 ); // Two objects on the stack 
CAge age2( 36 ); 
map.SetAt( "Bart", &agel ); 
map.SetAt( "Homer", &age2 ); 
ASSERT( map.GetCount() == 2 ); 
map.RemoveAl1l(); // CObject pointers removed; objects not removed 
ASSERT( map.GetCount() == @ ); 
ASSERT( map.IsEmpty() ); 
} // The two CAge objects are deleted when they go out of scope 


CMapStringToOb::RemoveKey 


CMapString ToOb::RemoveKey 
BOOL RemoveKey( const char* Key ); 


key 
The string used for map lookup. 


Looks up the map entry corresponding to the supplied key; then, if the key is 
found, removes the entry. This can cause memory leaks if the CObject object is 


not deleted elsewhere. 


TRUE if the entry was found and successfully removed; otherwise FALSE. 
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Example 


See Also 


Syntax 


Parameters 


Remarks 


CMapStringToOb map; 


map.SetAt( "Bart", new CAge( 13 ) ); 

map.SetAt( "Lisa", new CAge( 11 ) ); 

map.SetAt( "Homer", new CAge( 36 ) ); 

map.SetAt( "Marge", new CAge( 35 ) ); 

map.RemoveKey( "Lisa™ ); // memory leak: age object not deleted 
#ifdef _ DEBUG 

afxDump.SetDepth( 1 ); 

afxDump << “RemoveKey example: " << &map << “\\n"; 
dtendif 


The results from this program are as follows: 


RemoveKey example: A CMapStringToOb with 3 elements 
[Marge] = a CAge at $49A0 35 
[Homer] = a CAge at $495E 36 
[Bart] = a CAge at $4634 13 


CMapStringToOb::RemoveAll 


CMapStringToOb::SetAt 


void SetAt( const char* key, CObject* newValue ) 
throw( CMemoryException ); 


key 
The string that is the key of the new element. 


newValue 
The CObject pointer that is the value of the new element. 


The primary means to insert an element in a map. First, the key is looked up. If the 
key is found, then the corresponding value is changed; otherwise, a new key-value 
element is created. 
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Example CMapStringToOb map; 
CAge* pa; 


map.SetAt( "Bart", new CAge( 13 ) ); 
map.SetAt( "Lisa", new CAge( 11 ) ); // Map contains 2 elements 
ifdef _ DEBUG 
afxDump.SetDepth( 1 ); 
afxDump << “before Lisa's birthday: " << &map << "\\n"; 
dFendif 
if( map.Lookup( "Lisa", pa ) ) 
{ // CAge 12 pointer replaces CAge 11 pointer 
map.SetAt( "Lisa", new CAge( 12 ) ); 
delete pa; // Must delete CAge 11 to avoid memory leak 
} 
#Hifdef _DEBUG 
afxDump << “after Lisa's birthday: " << &map << “\\n"; 
dtendi f 


The results from this program are as follows: 


before Lisa's birthday: A CMapStringTo0Ob with 2 elements 


[Lisa] = a CAge at $493C 11 
[Bart] = a CAge at $4654 13 
after Lisa's birthday: A CMapStringTo0Ob with 2 elements 
[Lisa] = a CAge at $49C@ 12 
[Bart] = a CAge at $4654 13 


See Also CMapStringToOb::Lookup, CMapStringToOb::operator [ | 


386 CMapStringToOb::operator [ | 


Operators 


Syntax 


Remarks 


Example 


See Also 


CMapStringToOb::operator [ ] 


CObject*& operator [ ]( const char* key ); 


This operator is a convenient substitute for the SetAt member function. Thus it 
can be used only on the left side of an assignment statement (an I-value). If there is 
no map element with the specified key, then a new element is created. 


There is no “right side” (r-value) equivalent to this operator because there is a 
possibility that a key may not be found in the map. Use the Lookup member func- 
tion for element retrieval. 


CMapStringToOb map; 


mapL"Bart" ] 

mapL"Lisa"] 
#Hifdef _DEBUG 

afxDump.SetDepth( 1 ); 

afxDump << "Operator [] example: ™" << &map << "\\n"; 
dtendif 


new CAge( 13 ); 
new CAge( 11 ); 


The results from this program are as follows: 


Operator [] example: A CMapStringTo0Ob with 2 elements 
[Lisa] a CAge at $4A@2 11 
[Bart] a CAge at $497E 13 


CMapStringToOb::SetAt, CMapStringToOb::Lookup 
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class CMapStringToPtr : public CObject 


The CMapStringToPtr class supports maps of 
void pointers keyed by CString objects. eal le | 


CMapStringToPtr 


The member functions of CMapStringToPtr 
are similar to the member functions of class 
CMapStringToOb. Because of this similarity, you can use the 
CMapStringToOb reference documentation for member function specifics. 
Wherever you see a CObject pointer as a function parameter or return value, 
substitute a pointer to void. 


BOOL CMapStringlo0b::Lookup( const char* <key>, CObject*& <rValue> ) 
COnsSe: 


for example, translates to 


BOOL CMapStringToPtr::Lookup( const char* <key>, void*& <rValue> ) 
const; 


CMapStringToPtr incorporates the IMPLEMENT_ DYNAMIC macro to sup- 
port run-time type access and dumping to a CDumpContext object. If you need a 
dump of individual map elements, you must set the depth of the dump context to 
1 or greater. 


String-to-pointer maps may not be serialized. 


When a CMapStringToPtr object is deleted, or when its elements are removed, 
the CString key objects and the words are removed. 


#include <afxcoll.h> 


Public Members 


Construction/Destruction 


CMapStringToPtr Constructs a collection that maps CString objects 
to void pointers. 


~CMapStringToPtr Destroys a CMapStringToPtr object. 


CMapStringToPtr 


Operations 
Lookup 
SetAt 


operator [ | 


RemoveKey 
RemoveAll 
GetStartPosition 
GetNextAssoc 


Status 
GetCount 
IsEmpty 


Returns a void pointer, based on a CString value. 


Inserts an element into the map; replaces an 
existing element if a matching key is found. 


Inserts an element into the map—operator 
substitution for SetAt. 


Removes an element specified by a key. 
Removes all the elements from this map. 
Returns the position of the first element. 


Gets the next element for iterating. 


Returns the number of elements in this map. 


Tests for the empty-map condition (no elements). 
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class CMapStringToString : public CObject 


The CMapStringToString class supports maps of 
CString objects keyed by CString objects. 


. Es 
CObject | 
LST TOOT 


The member functions of CMapStringToString 
are similar to the member functions of class 
CMapStringToOb. Because of this similarity, you can use the 
CMapStringToOb reference documentation for member function specifics. 
Wherever you see a CObject pointer as a return value or ’output’ function parame- 
ter, substitute a pointer to char. Wherever you see a CObject pointer as an ’input’ 
function parameter, substitute a pointer to char. 


BOOL CMapStringToOb::Lookup( const char* <key>, CObject*& <rValue> ) 
const; 


for example, translates to 


BOOL CMapStringToString::Lookup( const char* <key>, CString& <rValue> ) 
const; 


CMapStringToString incorporates the IMPLEMENT_SERIAL macro to sup- 
port serialization and dumping of its elements. If a map is stored to an archive, 
either with the overloaded insertion operator or with the Serialize member func- 
tion, each element is, in turn, serialized. 


If you need a dump of individual CString-CString elements, you must set the 
depth of the dump context to | or greater. 


When a CMapStringToString object is deleted, or when its elements are re- 
moved, the CString objects are removed as appropriate. 


#include <afxcoll.h> 


Public Members 


Construction/Destruction 


CMapStringToString Constructs a collection that maps CString objects 
to CString objects. 


~CMapStringToString Destroys a CMapStringToString object. 


CMapStringToString 


Operations 
Lookup 


SetAt 
operator [ | 


RemoveKey 
RemoveAll 
GetStartPosition 
GetNextAssoc 


Status 
GetCount 
IsEmpty 


Returns a CString, using a CString value as a key. 


Inserts an element into the map; replaces an 
existing element if a matching key is found. 


Inserts an element into the map—operator 
substitution for SetAt. 


Removes an element specified by a key. 
Removes all the elements from this map. 
Returns the position of the first element. 


Gets the next element for iterating. 


Returns the number of elements in this map. 


Tests for the empty-map condition (no elements). 
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class CMapWordToOb : public CObject 


The CMapWordToOb class supports maps of 
CObject pointers keyed by 16-bit words. 


The member functions of CMapWordToOb 
are similar to the member functions of class 
CMapStringToOb. Because of this similarity, you can use the 
CMapStringToOb reference documentation for member function specifics. 
Wherever you see a CString or a const pointer to char as a function parameter or 
return value, substitute WORD. 


BOOL CMapStringToOb::Lookup( const char* <key>, CObject*& <rValue> ) 
const; 


for example, translates to 


BOOL CMapWordTo0b::Lookup( WORD <key>, CObject*& <rValue> ) const; 
CMapWordToOb incorporates the IMPLEMENT_SERIAL macro to support 
serialization and dumping of its elements. If a map is stored to an archive, either 


with the overloaded insertion operator or with the Serialize member function, 
each element is, in turn, serialized. 


If you need a dump of individual WORD-CObject elements, you must set the 
depth of the dump context to 1 or greater. 


When a CMapWordToOb object is deleted, or when its elements are removed, 
the CObject objects are deleted as appropriate. 


#include <afxcoll.h> 


Public Members 


Construction/Destruction 


CMapWordToOb Constructs a collection that maps words to 
CObject pointers. 


~CMapWordToOb Destroys a CMapWordToOb object. 


CMapWordToOb 


Operations 
Lookup 


SetAt 
operator [ | 


RemoveKey 
RemoveAll 
GetStartPosition 
GetNextAssoc 


Status 
GetCount 
IsEmpty 


Returns a CObject pointer, using a word value as 
a key. 


Inserts an element into the map; replaces an 
existing element if a matching Key is found. 


Inserts an element into the map—operator 
substitution for SetAt. 


Removes an element specified by a key. 
Removes all the elements from this map. 
Returns the position of the first element. 


Gets the next element for iterating. 


Returns the number of elements in this map. 


Tests for the empty-map condition (no elements). 
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class CMapWordToPtr : public CObject 


The CMapWordToPtr class supports maps of 
void pointers keyed by 16-bit words. ee 


CMapWordToPtr 


sao hase te 


The member functions of CMapWordToPtr 
are similar to the member functions of class 
CMapStringToOb. Because of this similarity, you can use the 
CMapStringToOb reference documentation for member function specifics. 
Wherever you see a CObject pointer as a function parameter or return value, sub- 
stitute a pointer to void. Wherever you see a CString or a const pointer to char as 
a function parameter or return value, substitute WORD. 


BOOL CMapStringTo0Ob::Lookup( const char* <key>, CObject*& <rValue> ) 
const; 


for example, translates to 

BOOL CMapWordToPtr::Lookup( WORD <key>, void*& <rValue> ) const; 
CMapWordToPtr incorporates the IMPLEMENT_DYNAMIC macro to sup- 
port run-time type access and dumping to a CDumpContext object. If you need a 


dump of individual map elements, you must set the depth of the dump context to 
1 or greater. 


Word-to-pointer maps may not be serialized. 


When a CMapWordToPtr object is deleted, or when its elements are removed, 
the words and the pointers are removed. The entities referenced by the pointers are 
not removed. 


#include <afxcoll.h> 


Public Members 


Construction/Destruction 


CMapWordToPtr Constructs a collection that maps words to void 
pointers. 


~CMapWordToPtr Destroys a CMapWordToPtr object. 


CMapWordToPtr 


Operations 
Lookup 
~SetAt 


operator [ ] 


RemoveKey 
RemoveAll 
GetStartPosition 
GetNextAssoc 


Status 
GetCount 
IsEmpty 


Returns a void pointer, using a word value as a key. 


Inserts an element into the map; replaces an 
existing element if a matching Key is found. 


Inserts an element into the map—operator 
substitution for SetAt. 


Removes an element specified by a key. 
Removes all the elements from this map. 
Returns the position of the first element. 


Gets the next element for iterating. 


Returns the number of elements in this map. 


Tests for the empty-map condition (no elements). 
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class CMDIChildWnd : public CFrameWnd 


The CMDIChild Whnd class provides the functionality 
of a Windows multiple document interface (MDI) 
child window, along with data and methods to manip- 
ulate the window. An MDI child window looks much 
like a typical application window, except that the MDI 
child window lacks a menu. The menu on the main 
application window applies to MDI child windows. 


To create a useful MDI child window for your application, derive a class from 
CMDIChildWnd. Add member variables to the derived class to store data 
specific to your application. Implement message-handler member functions and a 
message map in the derived class to specify what happens when messages are 
directed to the window. 


You create an MDI child window in two steps. First, call the constructor 
CMDIChildWnhd to construct the CMDIChildWnd object, then call the Create 
member function to create the MDI child window and attach it to the 
CMDIChild Wnd object. 


Construction can be a one-step process in a derived class. Write a constructor for 
the derived class and call Create from within the constructor. 


When the user terminates your MDI child window, destroy the CMDIChildWnd 
object, or call the DestroyWindow member function, which CMDIChildWnd 
inherits from class CWnd, to remove the CMDIChild Wnd and destroy its data 
structures. If you allocate any memory in the CMDIChildWnd object, override 
the CMDIChildWhd destructor to dispose of the allocations. 


See Also CWnd, CFrameWnd, CMDIFrameWnd 


Public Members 


Construction/Destruction 


CMDIChildWnd Called when a CMDIChild Wnhd object is 
constructed. 
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Initialization 
Create 


Operations 
MD {Destroy 
MD!IActivate 
MDIMaximize 
MDtIRestore 


GetParentFrame 


Protected Members 


Data Members 
m_pMDIFrameWnd 


Creates the Windows MDI child window as- 
sociated with the CMDIChild Wnd object. 


Destroys this MDI child window. 
Activates this MDI child window. 
Maximizes this MDI child window. 


Restores this MDI child window from maximized 
or minimized size. 


Returns the parent MDI frame. 


Points to the parent CMDIFrameWnd of this 
CMDIChildWnd. 
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Member Functions 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


CMDIChildWnd::CMDIChildWnd 


CMDIChildWnd0); 


Called when a CMDIChildWnhd object is constructed. The Windows MDI child 
window is not created until the Create member function is called. 


CMDIChild Wnd::Create 


CMDIChildWnd::Create 


BOOL Create( const char FAR* /pClassName, 
const char FAR* /pWindowName, DWORD dwSple = 0, 
const RECT S& rect = rectDefault, CMDIFrameWnd* pParentWnd = NULL ); 


lpClassName 
Points to a null-terminated character string that names the Windows class (a 
WNDCLASS struct). The class name can be any name registered with the 
afxRegisterWndClass function or any of the predefined control-class names. 
Should be NULL for a standard CMDIChild Wnd. 


lpWindowName 
Points to a null-terminated character string that represents the window name. 
Used as text for the title bar. 


dwStyle 
Specifies the window style attributes. See the CreateEx member function in the 
CWnd class for a full list of window styles. 


rect 
Contains the size and position of the window. The rectDefault value allows 
Windows to specify the size and position of the new CMDIChiid Wnd. 


pParentWnd 
Specifies the window’s parent. If NULL, the main application window is used. 
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Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Syntax 


Remarks 


See Also 


Creates the Windows MDI child window and attaches it to the CMDIChildWnd 
object. 


TRUE if successful; otherwise FALSE. 


CMDIChild Wnd::CMDIChildWnd 


CMDIChildWnd::GetParentFrame 


virtual CFrameWnd* GetParentFrame(); 


Returns the parent MDI frame. The actual parent, as returned by the GetParent 
member function, is a special, invisible window of type MDICLIENT. 


CMDIChildWnd::MDIActivate 


void MDIActivate(); 


An MDI child window is activated independently of the MDI frame window. 
When the frame becomes active, the child window that was last activated will be 
activated as well. 


CMDIFrameWnd::MD1GetActive, CWnd::OnNcActivate, 
CMDIFrameWnd::MDINext, WM_MDIACTIVATE 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


Syntax 
Remarks 


See Also 


CMDIChildWnd::MDIRestore 399 


CMDIChildWnd::MDIDestroy 


void MDIDestroy(); 


Destroys this MDI child window. 


Removes the title of the child window from the frame window and deactivates the 
child window. 


WM_MDIDESTROY, CMDIChild Wnd::Create 


CMDIChildWnd::MDIMaximize 


void MDIMaximize(); 


Maximizes this MDI child window. When a child window is maximized, Win- 
dows resizes it to make its client area fill the client window. Windows places the 
child window’s Control menu in the frame’s menu bar so that the user can restore 
or close the child window, and adds the title of the child window to the frame- 
window title. 


WM_MDIMAXIMIZE, CMDIChildWnd::MDIRestore 


CMDIChildWnd::MDIRestore 


void MDIRestore(); 
Restores this MDI child window from maximized or minimized size. 


CMDIChildWnd::MDIMaximize, WM_MDIRESTORE 


400 = CMDIChildWnd::m_pMDIFrameWnd 


Data Members 


CMDIChildWnd::m_pMDIFrameWnd 


Remarks Points to the parent CMDIFrameWnd of this CMDIChildWnd. 


See Also CMDIChildWnd:GetParentFrame, CMDIFrameWnd 
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class CMDIFrameWnd : public CFrameWnd 


The CMDIFrameWnd class provides the functional- 
ity of a Windows multiple document interface (MDI) 
frame window, and also provides members for manag- 
ing the window. 


To create a useful MDI frame window for your appli- 

cation, derive a class from CMDIFrameWnd. Add 

member variables to the derived class to store data specific to your application. 
Implement message-handler member functions and a message map in the derived 
class to specify what happens when messages are directed to the window. 


You create an MDI frame window in two steps. First, call the constructor 
CMDIFrameWnd to construct the CMDIFrameWnd object, then call the 
Create member function to create the MDI frame window and attach it to the 
CMDIFrameWnd object. 


Construction can be a one-step process in a derived class. Write a constructor for 
the derived class and call Create from within the constructor. 


When the user terminates your MDI frame window, destroy the 
CMDIFrameWnd object, or call the DestroyWindow member function, which 
CMDIFrameWnd inherits from class CWnd, to remove the CMDIFrameWnd 
and destroy its data structures. If you allocate any memory in the 
CMDIFrameWnd object, override the CMDIFrameWnd destructor to 

dispose of the allocations. 


See Also CWnd, CFrameWnd, CMDIChildWnd 


Public Members 


Construction/Destruction 
CMDIFrameWnd Constructs a CMDIFrameWnd. 


Initialization 


Create Creates and attaches the Windows MDI frame win- 
dow associated with the CMDIFrameWnd object. 
CreateClient Fills outa CLIENTCREATESTRUCT and 


creates a Windows MDICLIENT window for this 
CMDIFrameWnd. Called by the OnCreate mem- 
ber function. 


CMDIFrameWnd 


Operations 
MDtIActivate 
MDICascade 
MD1IGetActive 


MDIIconArrange 
MDIMaximize 
MDINext 


MDtIRestore 
MDISetMenu 


MDITile 
GetChildFrame 


Data Members 


m_hWndMDIClient 


Activates a different MDI child window. 
Arranges all child windows in a cascade format. 


Retrieves the current active MDI child window, 
along with a flag indicating whether the child is 
maximized or not. 


Arranges all minimized document child windows. 
Maximizes an MDI child window. 


Activates the child window immediately behind 
the currently active child window and places the 
currently active child window behind all other 
child windows. 


Restores an MDI child window from maximized 
or minimized size. 


Replaces the menu of an MDI frame window, the 
Window pop-up menu, or both. 


Arranges all child windows in a tiled format. 
Returns the active MDI child. 


The HWND for the MDI client window. 
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Member Functions 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


CMDIFrameWnd::CMDIFrameWnd 


CMDIFrameWnd(); 


Constructs a CMDIFrameWnd object. The Windows MDI frame window is not 
created and attached to the CMDIFrameWnd object until the Create member 
function is called. 


CMDIFrameWnd::Create 


CMDIFrameWnd::Create 


BOOL Create( const char FAR* [pClassName, 
const char FAR* /pWindowName, DWORD dwSvbyle, const RECT & rect, 
const CWnd* pParentWnd, const char FAR* [pMenuName ); 


lpClassName 
Points to a null-terminated character string that names the Windows class (a 
WNDCLASS struct). The class name can be any name registered with the 
afxRegisterWndClass function or any of the predefined control-class names. 
If NULL, uses the predefined default CMDIFrameWnd attributes. 


lpWindowName 
Points to a null-terminated character string that represents the window name. 
Used as text for the title bar. 


dwStyle 
Specifies the window style attributes. See the CreateEx member function in the 
CWnd class for a full list of window styles. 


rect 
Contains the size and position of the window. The rectDefault value allows 
Windows to specify the size and position of the new CMDIFrameWnd. 
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pParentWnd 
Specifies the parent window of this MDI frame window. This parameter should 
be NULL for top-level MDI frame windows. 


lpMenuName 
Identifies the name of the menu resource to be used with the window. Use 
MAKEINTRESOURCE if the menu has an integer ID instead of a string. 
This parameter can be NULL. 


Remarks Creates the Windows MDI frame window and attaches it to the 
CMDIFrameWnd object. 
Return Value TRUE if successful; otherwise FALSE. 


See Also CMDIFrameWnd::CMDIFrameWnd 


CMDiFrameWnd::CreateClient 


Syntax virtual BOOL CreateClient( LPCREATESTRUCT [pCreateStruct, 
CMenu* pWindowMenu ); 


Parameters [p Create Struct 
Pointer to a CREATESTRUCT structure. 


pWindowMenu 
Pointer to the window pop-up menu. 


Remarks Creates the MDI client window that manages the CMDIChildWnds and fills out 
a CLIENTCREATESTRUCT. 


CreateClient should be called if you override the OnCreate member function. 
Return Value TRUE if successful; otherwise FALSE. 


See Also CMDIFrameWnd::CMDIFrameWnd, CMDIFrameWnd::Create 
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CMDIFrameWnd::GetChildFrame 


syntax virtual CFrameWnd* GetChildFrame(); 


Return Value Returns the active MDI child if successful. Returns a pointer to the 
CMDIFrameWnd if unsuccessful. 


See Also CMDIFrameWnd::MD1GetActive 


CMDIFrameWnd::MDlActivate 


Syntax void MDIActivate( CWnd* pWndActivate ); 


Parameters pWndActivate 
Points to the MDI child window to be activated. 


Remarks Activates a different MDI child window. The WM_MDIACTIVATE message 
is sent to both the child window being activated and the child window being 
deactivated. 


An MDI child window is activated independently of the MDI frame window. 
When the frame becomes active, the child window that was last activated is sent a 
WM_NCACTIVATE message to draw an active window frame and caption bar, 
but it does not receive another WM_MDIACTIVATE message. 


See Also CMDIFrameWnd::MD!1GetActive, CMDIFrameWnd::MDINext, 
WM_ACTIVATE, WM_NCACTIVATE 
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Syntax 
Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


CMDIiFrameWnd::MDICascade 


void MDICascade(); 
Arranges all the MDI child windows in a cascade format. 


CMDIFrameWnd::MDIIconArrange, CMDIFrameWnd::MDITile, 
WM_MDICASCADE 


CMDIFrameWnd::MDIGetActive 


CMDIChildWnd* MDIGetActive( BOOL* pbMaximized = NULL ) const; 


pbMaximized 
Set to TRUE on return if the window is maximized; otherwise FALSE. 


Retrieves the current active MDI child window, along with a flag indicating 
whether the child window is maximized. 


A pointer to the active MDI child window. 


CMDIFrameWnd::MDIActivate, WM_MDIGETACTIVE 


CMDIFrameWnd::MDilconArrange 


void MDIIconArrange(); 


Arranges all minimized document child windows. It does not affect child windows 
that are not minimized. 


CMDIFrameWnd::MDICascade, CMDIFrameWnd::MDITile, 
WM_MDITCONARRANGE 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


See Also 
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CMDIFrameWnd::MDIMaximize 


void MDIMaximize( CWnd* pWnd ); 


pWnd 
Points to the window to maximize. 


Maximizes an MDI child window. When a child window is maximized, Windows 
resizes it to make its client area fill the client window. Windows places the child 
window’s Control menu in the frame’s menu bar so that the user can restore or 
close the child window, and adds the title of the child window to the frame- 
window title. 


WM_MDIMAXIMIZE, CMDIFrameWnd::MDIRestore 


CMDIFrameWnd::MDINext 


void MDINext(); 


Activates the child window immediately behind the currently active child window 
and places the currently active child window behind all other child windows. 


If the currently active MDI child window is maximized, restores the currently ac- 
tive child and maximizes the newly activated child. 


CMDIFrameWnd::MDIActivate, CMDIFrameWnd::MDIGetActive, 
WM_MDINEXT 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CMDIFrameWnd::MDIRestore 


void MDIRestore( CWnd* pWahd ); 


pWnd 
Points to the window to restore. 


Restores an MDI child window from maximized or minimized size. 


CMDIFrameWwnd::MDIMaximize, WM_MDIRESTORE 


CMDIFrameWnd::MDISetMenu 


CMenu* MDISetMenu( CMenu* pFrameMenu, CMenu* pWindowMenu ); 


pFrameMenu 
Specifies the menu of the new frame-window menu. If NULL, the menu is not 
changed. 


pWindowMenu 
Specifies the menu of the new Window pop-up menu. If NULL, the menu is 
not changed. 


Replaces the menu of an MDI frame window, the Window pop-up menu, or both. 


After calling MDISetMenu, an application must call the DrawMenuBar member 
function to update the menu bar. 


If this call replaces the Window pop-up menu, MDI child-window menu items are 
removed from the previous Window menu and added to the new Window pop-up 
menu. 


If an MDI child window is maximized and this call replaces the MDI frame- 
window menu, the Control menu and restore controls are removed from the 
previous frame-window menu and added to the new menu. 


CMDIFrameWnd::MDITile 409 


Return Value A pointer to the frame-window menu replaced by this message. The pointer may 
be temporary, and should not be stored for later use. 


See Also CWnd::DrawMenuBar, WM_MDISETMENU 


CMDIFrameWnd::MDITile 


Syntax void MDITile(); 


void MDITile( int nType ); 


Parameters nType 
Specifies a tiling flag. This parameter can be one of the following flags: 


Value Meaning 
MDITILE_ HORIZONTAL Tiles MDI child windows horizontally 
(one window appears beside another). 


MDITILE_SKIPDISABLED Prevents disabled MDI child windows 
from being tiled. 


MDITILE_ VERTICAL Tiles MDI child windows vertically 
(one window appears above another). 


Remarks Arranges all child windows in a tiled format. 


See Also CMDIFrameWnd::MDICascade, CMDIFrameWnd::MDIIconArrange, 
WM_MDITILE 


410 CMDIFrameWnd::m_hWndMDIClient 


Data Members 


CMDIFrameWnd::m_hWndMDIClient 


Remarks The HWND for the MDI client window owned by CMDIFrameWnd. 
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class CMemFile : public CFile 


CMemFile is the CFile-derived class that supports 
in-memory files. These in-memory files behave like 
binary disk files except that bytes are stored in RAM. 
An in-memory file is a useful means of transferring 
raw bytes or serialized objects between independent 
processes. 


Contiguous memory is automatically allocated in specified increments, and it is de- 
leted when the object is destroyed. You can access this memory through a pointer 
supplied by a member function. 


#include <afx.h> 


Comments The following CFile functions are not implemented for CMemFile: 
= Duplicate 
=" LockRange 
=» UnlockRange 


If you call these functions on a CMemFile object, you will get a 
CNotSupportedException. 


The data member CFile::m_hFile is not used and has no meaning. 


Derivation If you derive a class from CMemFile, you must use the protected memory- 
allocation functions listed above, overriding them as necessary. If you need global 
memory access from the Windows medium model, for example, derive a class 
with the four protected functions overridden. Your replacement functions should 
call the Windows GlobalAlloc family of functions. 


Public Members 


Construction/Destruction 


CMemFile Constructs a memory file using internally allocated 
memory. 


~CMemFile Closes the memory file, freeing allocated memory. 
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Member Functions 


Syntax 


Parameters 


Remarks 


Example 


Syntax 


Remarks 


CMemFile::CMemFile 


CMemFile( UINT nGrowBytes = 1024 ) 
throw ( CFileException, CMemoryException ); 


nGrowBytes 
The memory-allocation increment in bytes. 


This constructor allocates memory and opens an empty memory file. 


CMemFile f; // ready to use - no Open necessary 


CMemFile::~CMemFile 


virtual ~CMemFile(); 


This destructor frees all allocated memory associated with this memory file, effec- 
tively closing it. 
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class CMemoryException : public CException 


A CMemoryException object represents an out-of- 
memory exception condition. No further qualification 
is necessary or possible. Memory exceptions are 
thrown automatically by new. If you write your own 
memory functions, using malloc, for example, then 
you are responsible for throwing memory exceptions. 


#include <afx.h> 


Public Members 


Construction/Destruction 


CMemoryException Constructs a CMemoryException object. 


Member Functions 


CMemoryException::CMemoryException 


Syntax CMemoryException(; 


Remarks Constructs a CMemoryException object. Do not use this constructor directly, but 
rather call the global function AfxThrowMemoryException. This global function 
can succeed in an out-of-memory situation because it constructs the exception ob- 
ject in previously allocated memory. 


See Also Chapter 5, “Exception Processing,” AfxThrowMemoryException 
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class CMenu : public CObject 


The CMenu class is an encapsulation of the 
Windows HMENU. It provides member functions 
for creating, tracking, updating, and destroying 
menus. When you create a CMenu object, you 
associate it with a handle to a menu resource. Then you can use the class member 
functions to manage the menu. 


See Also CObject 


Public Members 


Construction/Destruction 


CMenu Constructs a CMenu object. 

~CMenu Destroys a CMenu object. 

Initialization 

Attach Attaches a Windows menu handle to a CMenu 
object. 

Detach Detaches a Windows menu handle from a CMenu 
object and returns the handle. 

CreateMenu Creates an empty menu and attaches it toa 
CMenu object. 

CreatePopupMenu Creates an empty pop-up menu and attaches it to a 
CMenu object. 

LoadMenu Loads a menu resource from the executable file 


and attaches it to a CMenu object. 


LoadMenuIndirect Loads a menu from a menu template in memory 
and attaches it to a CMenu object. 


DestroyMenu Destroys the menu attached to a CMenu object 
and frees any memory that the menu occupied. 


Menu Operations 
DeleteMenu 


TrackPopupMenu 


Menu Item Operations 


AppendMenu 
CheckMenulItem 


EnableMenulItem 
GetMenulItemCount 


GetMenultemID 
GetMenuState 


GetMenuString 
GetSubMenu 


InsertMenu 
ModifyMenu 
RemoveMenu 


SetMenulItemBitmaps 
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Deletes a specified item from the menu. If the 
menu item has an associated pop-up menu, de- 
stroys the handle to the pop-up menu and frees the 
memory used by it. 


Displays a floating pop-up menu at the specified 
location and tracks the selection of items on the 
pop-up menu. 


Appends a new item to the end of this menu. 


Places check marks next to or removes check 
marks from menu items in the pop-up menu. 


Enables, disables, or dims (grays) a menu item. 


Determines the number of items in a pop-up or top- 
level menu. 


Obtains the menu-item identifier for a menu item 
located at the specified position. 


Returns the status of the specified menu item or 
the number of items in a pop-up menu. 


Retrieves the label of the specified menu item. 
Retrieves a pointer to a pop-up menu. 


Inserts a new menu item at the specified position, 
moving other items down the menu. 


Changes an existing menu item at the specified 
position. 

Deletes a menu item with an associated pop-up 
menu from the specified menu. 


Associates the specified check-mark bitmaps with 
a menu item. 
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Member Functions 


CMenu::AppendMenu 


Syntax BOOL AppendMenu( UINT nFlags, UINT nIDNewltem = 0, 
const char FAR* /pNewItem = NULL ); 


BOOL AppendMenu( UINT nFlags, UINT nIDNewlItem, 
const CBitmap* pBmp ); 


Parameters nFlags 
Specifies information about the state of the new menu item when it is added to 
the menu. It consists of one or more of the values listed in the Remarks section. 


nIDNewltem 
Specifies either the command ID of the new menu item or, if nFlags is 
set to MF_POPUP, the menu handle (HMENU) of a pop-up menu. The 
nIDNewltem parameter is ignored (not needed) if nFlags is set to 
MF_SEPARATOR. 


lpNewItem 
Specifies the content of the new menu item. The interpretation of IpNewltem 
depends on the setting of nFlags as shown below: 


nFlags Interpretation of IlpNewItem 


MF_OWNERDRAW Contains an application-supplied 32-bit value 
that the application can use to maintain addi- 
tional data associated with the menu item. This 
32-bit value is available to the application when 
it processes WM_MEASUREITEM and 
WM_DRAWITEM messages. 


MF_STRING Contains a pointer to a null-terminated string. 
This is the default interpretation. 


The [pNewItem parameter is ignored (not needed) if nFlags is set to 
MF_SEPARATOR. 


pBmp 
Points to a CBitmap object that will be used as the menu item. 


Remarks Appends a new item to the end of a menu. The application can specify the state of 
the menu item by setting values in nFlags. When nIDNewlItem specifies a pop-up 
menu, it becomes part of the menu to which it is appended. If that menu is de- 
stroyed, the appended menu will also be destroyed. An appended menu should be 
detached from a CMenu object to avoid conflict. 
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Note MF_STRING and MF_OWNERDRAW< are not valid for the bitmap ver- 


sion of AppendMenu. 


The following list describes the flags that may be set in nFlags: 


Value 


MF_CHECKED 


MF_DISABLED 


MF_ENABLED 


MF_GRAYED 


MF_MENUBARBREAK 


MF_MENUBREAK 


MF_OWNERDRAW 


MF_POPUP 


Interpretation of nFlags 


Acts as a toggle in conjunction with 
MF_UNCHECKED to place the default check 
mark next to the item. When the application 
supplies check-mark bitmaps (see 
SetMenulItemBitmaps), the “check mark on” 
bitmap is displayed. 


Disables the menu item so that it cannot be 
selected, but does not dim it. 


Enables the menu item so that it can be selected, 
and restores it from its dimmed state. 


Disables the menu item so that it cannot be 
selected, and dims it. 


Places item on a new line in static menus or in a 
new column in pop-up menus. The new pop-up | 
menu column will be separated from the old 
column by a vertical dividing line. 


Places item on a new line in static menus or in a 
new column in pop-up menus. No dividing line is 
placed between the columns. 


Specifies that the item is an owner-draw item. 
When the menu is displayed for the first time, the 
window that owns the menu receives a 
WM_MEASUREITEM message, which 
retrieves the height and width of the menu item. 
The WM_DRAWITEM message is the one sent 
whenever the owner must update the visual 
appearance of the menu item. This option is not 
valid for a top-level menu item. 


Specifies that the menu item has a pop-up menu 
associated with it. The ID parameter specifies a 
handle to a pop-up menu that is to be associated 
with the item. This is used for adding either a top- 
level pop-up menu or a hierarchical pop-up menu 
to a pop-up menu item. 
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Value Interpretation of nFlags 


MF_SEPARATOR Draws a horizontal dividing line. Can only be used 
in a pop-up menu. This line cannot be dimmed, 
disabled, or highlighted. Other parameters are 


ignored. 
MF_STRING Specifies that the menu item is a character string. 
MF_UNCHECKED Acts as a toggle in conjunction with 


MF_CHECKED to remove a check mark next to 
the item. When the application supplies check- 
mark bitmaps (see SetMenulItemBitmaps), the 
“check mark off” bitmap is displayed. 


Each of the following groups lists flags that are mutually exclusive and cannot be 
used together: 


MF_DISABLED, MF_ENABLED, and MF_GRAYED 


MF_STRING, MF_OWNERDRAW, MF_SEPARATOR, and the bitmap 
version 


MF_MENUBARBREAK and MF_ MENUBREAK 
MF_CHECKED and MF_ UNCHECKED 


Whenever a menu that resides in a window is changed (whether or not the window 
is displayed), the application should call CWnd::DrawMenuBar. 


Return Value TRUE if the function is successful; otherwise FALSE. 
See Also CWnd::DrawMenuBar, CMenu::InsertMenu, CMenu::RemoveMenu, 


CMenu::SetMenuItemBitmaps, CMenu::Detach, CMenu::~CMenu, 
::AppendMenu 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 
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CMenu::Attach 


BOOL Attach( HMENU hMenu); 


hMenu 
Specifies a handle to a Windows menu. 


Attaches an existing Windows menu to a CMenu object. This function should not 
be called if a menu is already attached to the CMenu object. The menu handle is 
stored in the m_hMenu data member. 


TRUE if the operation was successful; otherwise FALSE. 


CMenu::Detach, CMenu::CMenu 


CMenu::CheckMenultem 


UINT CheckMenultem( UINT n/DCheckItem, UINT nCheck ); 


n[DChecklItem 
Specifies the menu item to be checked, as determined by nCheck. 


nCheck 
Specifies how to check the menu item and how to determine the item’s position 
in the menu. The nCheck parameter can be a combination of MF_ CHECKED 
or MF_UNCHECKED with MF_BYPOSITION or MF_BYCOMMAND 
flags. These flags can be combined by using the bitwise OR operator. They 
have the following meanings: 


Value Interpretation of nCheck 


MF_ BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This is the default 
if neither MF_ BYCOMMAND nor 
MF_BYPOSITION is set. 


MF_BYPOSITION Specifies that the parameter gives the position of 
the existing menu item (the first item is at 
position QO). 
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Remarks 


Return Value 


See Also 


Syntax 
Remarks 


See Also 


Value Interpretation of nCheck 


MF_CHECKED Acts as a toggle in conjunction with 
MF_UNCHECKED to place the default check 
mark next to the item. When the application 
supplies check-mark bitmaps (see 
SetMenultemBitmaps), the “check mark on” 
bitmap is displayed. 


MF_UNCHECKED Acts as a toggle in conjunction with 
MF_CHECKED to remove a check mark next 
to the item. When the application supplies check- 
mark bitmaps (see SetMenuItemBitmaps), the 
“check mark off’ bitmap is displayed. 


Adds check marks to or removes check marks from menu items in the pop-up 
menu. The nIDCheckltem parameter specifies the item to be modified. 


The nIDCheckItem parameter may identify a pop-up menu item as well as a menu 
item. No special steps are required to check a pop-up menu item. Top-level menu 
items cannot be checked. A pop-up menu item must be checked by position since 
it does not have a menu-item identifier associated with it. 


The previous state of the item: MF_CHECKED or MF_CHECKED, or —1 if 
the menu item did not exist. 


CMenu::GetMenuState, ::;CheckMenultem 


CMenu::CMenu 


CMenu(); 
The menu is not created until you call one of the create or load member functions. 


CMenu::CreateMenu, CMenu::CreatePopupMenu, CMenu::LoadMenu, 
CMenu::LoadMenulIndirect, CMenu::~CMenu, CMenu::Attach 


Syntax 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 
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CMenu::~CMenu 


virtual ~CMenu(); 


Destroys the attached menu. If the m_hMenu data member was appended or in- 
serted into another menu, it should be detached from this CMenu object before 
the destructor destroys it. 


CMenu::CMenu, CMenu::DestroyMenu, CMenu::Detach 


CMenu::CreateMenu 


BOOL CreateMenu(); 


Creates a menu and attaches it to the CMenu object. 


The menu is initially empty. Menu items can be added by using the AppendMenu 
or InsertMenu member functions. 


If the menu is assigned to a window, it is automatically destroyed when the win- 
dow is destroyed. 


TRUE if the menu was created successfully; otherwise FALSE. 


CMenu::CMenu, CMenu::DestroyMenu, CMenu::InsertMenu, 
CWnd::SetMenu, ::CreateMenu 


CMenu::CreatePopupMenu 
BOOL CreatePopupMenu(Q); 


Creates a pop-up menu and attaches it to the CMenu object. 


The menu is initially empty. Menu items can be added by using the AppendMenu 
or InsertMenu member functions. The application can add the pop-up menu to an 
existing menu or pop-up menu. TrackPopupMenu may be used to display this 

menu as a floating pop-up menu. 


a 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


If the menu is assigned to a window, it is automatically destroyed when the win- 
dow is destroyed. If the menu is added to an existing menu, it is automatically de- 
stroyed when that menu is destroyed. 


TRUE if the pop-up menu was successfully created; otherwise FALSE. 


CMenu::CreateMenu, CMenu::InsertMenu, CWnd::SetMenu, 
CMenu::TrackPopupMenu, ::CreatePopupMenu 


CMenu::DeleteMenu 


BOOL DeleteMenu( UINT nPosition, UINT nFlags ); 


nPosition 
Specifies the menu item that is to be deleted, as determined by nFlags. 


nFlags 
The following list shows how nFlags 1s used to interpret nPosition. 


nFlags Interpretation of nPosition 


MF_BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This is the default 
if neither MF_BYCOMMAND nor 
MF_BYPOSITION is set. 


MF_BYPOSITION Specifies that the parameter gives the position of 
the existing menu item (the first item is at 
position Q). 


Deletes an item from the menu. If the menu item has an associated pop-up menu, 
DeleteMenu destroys the handle to the pop-up menu and frees the memory used 
by the pop-up menu. 


Whenever a menu that resides in a window is changed (whether or not the window 
is displayed), the application must call CWnd::DrawMenuBar. 


TRUE if the function is successful; otherwise FALSE. 


CWnd::DrawMenuBar, ::DeleteMenu 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 
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CMenu::DestroyMenu 
BOOL DestroyMenuQ); 


Destroys the menu and any Windows system resources that were used. The menu 
is detached from the CMenu object before it is destroyed. The Windows 
DestroyMenu function is automatically called in the CMenu destructor. 

TRUE if the menu is destroyed; otherwise FALSE. 


CMenu::~CMenu, ::DestroyMenu 


CMenu::Detach 


HMENU DetachQ); 


Detaches a Windows menu from a CMenu object and returns the handle. The 
m_hMenu data member is set to NULL. 


The handle, of type HMENU, to a Windows menu, if successful; otherwise 
NULL. 


CMenu::~CMenu, CMenu::Attach 


CMenu::EnableMenultem 


UINT EnableMenultem( UINT n/DEnableltem, UINT nEnable ); 


nIDEnableltem 
Specifies the menu item to be enabled, as determined by nEnable. 


nEnable 
Specifies the action to take. It can be a combination of MF_DISABLED, 
MF_ENABLED, or MF_ GRAYED, with MF_BYCOMMAND or 
MF_BYPOSITION. These values can be combined by using the bitwise-OR 
operator. These values have the following meanings: 
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Value Interpretation of nEnable 


MF_BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This is the default 
if neither MF_ BYCOMMAND nor 
MF_BYPOSITION is set. 


MF_BY POSITION Specifies that the parameter gives the position of 
the existing menu item (the first item is at 
position 0). 


MF_DISABLED Disables the menu item so that it cannot be 
selected, but does not dim it. 

MF_ENABLED Enables the menu item so that it can be selected, 
and restores it from its dimmed state. 

MF_GRAYED Disables the menu item so that it cannot be 


selected, and dims it. 


Remarks Enables, disables, or dims a menu item. 

Return Value Previous state (MF_ DISABLED, MF_ ENABLED, or MF_GRAYED) or —1 if 
not valid. 

See Also CMenu::GetMenuState, ::EnableMenultem 


CMenu::GetMenultemCount 


Syntax UINT GetMenulItemCount() 

Remarks Determines the number of items in a pop-up or top-level menu. 

Return Value The number of items in the menu if the function is successful; otherwise —1. 
See Also CWnd::GetMenu, CMenu::GetMenultemID, CMenu::GetSubMenu, 


::<GetMenultemCount 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


syntax 


Parameters 


Remarks 
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CMenu::GetMenultemID 


UINT GetMenultemID( int nPos ) const; 


nPos 
Specifies the position (zero-based) of the menu item whose ID 1s being re- 
trieved. 


Obtains the menu-item identifier for a menu item located at the position defined 
by nPos. 


The item ID for the specified item in a pop-up menu if the function is successful. 
If the specified item is a pop-up menu (as opposed to an item within the pop-up 
menu), the return value is —1. If nPos corresponds to a SEPARATOR menu item, 
the return value is 0. 


CWnd::GetMenu, CMenu::GetMenultemCount, CMenu::GetSubMenu, 
::;<GetMenultemID 


CMenu::GetMenuState 


UINT GetMenuState( UINT n/ID, UINT nFlags ) const; 


nID 
Specifies the menu item ID, as determined by nFlags. 


nFlags 
Specifies the nature of nJD. It can be one of the following values: 


Value Interpretation of nFlags 


MF_BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This 1s the default 
if neither MF_BYCOMMAND nor 
MF_BYPOSITION is set. 


MF_BYPOSITION Specifies that the parameter gives the position of 
the existing menu item (the first item is at 
position 0). 


Returns the status of the specified menu item or the number of items in a pop-up 
menu. 
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Return Value The value —1 if the specified item does not exist. If nJd identifies a pop-up menu, 
the high-order byte contains the number of items in the pop-up menu and the low- 
order byte contains the menu flags associated with the pop-up menu. Otherwise 
the return value is a mask (Boolean OR) of the values from the following list (this 
mask describes the status of the menu item that n/d identifies): 


Value Meaning 


MF_CHECKED Acts as a toggle in conjunction with 
MF_UNCHECKED to place the default check 
mark next to the item. When the application 
supplies check-mark bitmaps (see 
SetMenultemBitmaps), the “check mark on” 


bitmap is displayed. 

MF_DISABLED Disables the menu item so that it cannot be 
selected, but does not dim it. 

MF_ENABLED Enables the menu item so that it can be selected, 
and restores it from its dimmed state. 

MF_GRAYED Disables the menu item so that it cannot be 


selected, and dims it. 


MF_MENUBARBREAK Places item on a new line in static menus or in a 
new column in pop-up menus. The new pop-up 
menu column will be separated from the old 
column by a vertical dividing line. 


MF_MENUBREAK Places item on a new line in static menus or in a 
new column in pop-up menus. No dividing line is 
placed between the columns. 


MF_SEPARATOR Draws a horizontal dividing line. Can only be 
used in a pop-up menu. This line cannot be 
dimmed, disabled, or highlighted. Other 
parameters are ignored. 


MF_UNCHECKED Acts as a toggle in conjunction with 
MF_CHECKED to remove a check mark next 
to the item. When the application supplies check- 
mark bitmaps (see SetMenultemBitmaps), the 
“check mark off’ bitmap is displayed. 


See Also ::;GetMenuState, CMenu::CheckMenultem, CMenu::EnableMenulItem 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CMenu::GetMenuString 


int GetMenuString( UINT n/DItem, LPSTR I[pString, int nMaxCount, 
UINT nFlags ) const; 


nlDItem 
Specifies the integer identifier of the menu item or the offset of the menu item 
in the menu, depending on the value of nFlags. 

[pString 
Points to the buffer that is to receive the label. You can pass a CString object 
for this parameter. 


nMaxCount 
Specifies the maximum length (in bytes) of the label to be copied. If the label is 
longer than the maximum specified in nMaxCount, the extra characters are trun- 
cated. 


nFlags 


nFlags Interpretation of nIDItem 
MF_BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This is the default 


if neither MF_BYCOMMAND nor 
MF_BYPOSITION is set. 


MF_BYPOSITION Specifies that the parameter gives the position 
of the existing menu item (the first item 1s at 
position 0). 


Copies the label of the specified menu item to the specified buffer. 


The nMaxCount parameter should be one larger than the number of characters in 
the label to accommodate the null character that terminates a string. 


Specifies the actual number of bytes copied to the buffer, not including the null 
terminator. 


CWnd::GetMenu, CMenu::GetMenultemID, ::GetMenuString 
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CMenu::GetSubMenu 


Syntax CMenu* GetSubMenu( int nPos ) const; 


Parameters nPos 
Specifies the position of the pop-up menu contained in the menu. Position 
values start at O for the first menu item. 


Remarks Retrieves the CMenu object of a pop-up menu. 


Return Value A pointer to a CMenu object whose m_hMenu member contains a handle to the 
pop-up menu if a pop-up menu exists at the given position; otherwise NULL. If a 
CMenu object does not exist, then a temporary one is created. The CMenu 
pointer returned should not be stored. 


See Also ::GetSubMenu 


CMenu::InsertMenu 


Syntax BOOL InsertMenu( UINT nPosition, UINT nFlags, UINT nIDNewltem = 0, 
const char FAR* /pNewItem = NULL ); 


BOOL InsertMenu( UINT nPosition, UINT nFlags, UINT nIDNewltem, 
const CBitmap* pBmp ); 


Parameters nPosition 
Specifies the menu item before which the new menu item is to be inserted. The 
interpretation of nPosition depends on the setting of nFlags, as shown in the fol- 
lowing list: 
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nFlags Interpretation of nPosition 


MF_BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This is the default 
if neither MF_BY COMMAND nor 
MF_BYPOSITION is set. 


MF_BYPOSITION Specifies that the parameter gives the position of 
the existing menu item (the first item is at 
position 0). 


If nPosition is —1, the new menu item 1s 
appended to the end of the menu. 


nFlags 
Specifies how nPosition is interpreted and information about the state of the 
new menu item when it is added to the menu. For a list of the flags that may be 
set, see the AppendMenu member function. To specify more than one value, 
use the bitwise OR operator to combine them with the MF_ BYCOMMAND 
or MF_BYPOSITION flag. 


nIDNewltem 
Specifies either the command ID of the new menu item or, if nFlags is set to 
MF_POPUP, the menu handle (HMENU) of the pop-up menu. n/DNewlItem 1s 
ignored (not needed) if nFlags is set to MF_SEPARATOR. 


lpNewltem 
Specifies the content of the new menu item. The interpretation of IpNewltem 
depends on the setting of nFlags as shown below: 


nFlags Interpretation of IpNewItem 


MF_OWNERDRAW Contains an application-supplied 32-bit value that 
the application can use to maintain additional 
data associated with the menu item. This 32-bit 
value is available to the application when it 
processes WM_MEASUREITEM and 
WM_DRAWITEM messages. 


MF_STRING Contains a long pointer to a null-terminated 
string. This is the default interpretation. 


The [pNewItem parameter is ignored (not needed) if nFlags is set to 
MF_SEPARATOR. 

pBmp 
Points to a CBitmap object that will be used as the menu item. 
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Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Inserts a new menu item at the position specified by nPosition and moves other 
items down the menu. The application can specify the state of the menu item by 
setting values in nFlags. 


Whenever a menu that resides in a window is changed (whether or not the window 
is displayed), the application should call CWnd::DrawMenuBar. 


When nIDNewlItem specifies a pop-up menu, it becomes part of the menu in which 
it is inserted. If that menu is destroyed, the inserted menu will also be destroyed. 
An inserted menu should be detached from a CMenu object to avoid conflict. 


TRUE if the function is successful; otherwise FALSE. 


CMenu::AppendMenu, CWnd::DrawMenuBar, 
CMenu::SetMenultemBitmaps, CMenu::Detach, CMenu::~CMenu, 
::InsertMenu 


CMenu::LoadMenu 


BOOL LoadMenu( const char FAR* [pMenuName ); 
BOOL LoadMenu( UINT n/DMenu ); 


[pMenuName 


Points to a null-terminated string that contains the name of the menu resource 
to load. 


nlDMenu 
Specifies the menu ID of the menu resource to load. 


Loads a menu resource from the application’s executable file and attaches it to the 
CMenu object. 


TRUE if the menu resource was loaded successfully; otherwise FALSE. 


CMenu::AppendMenu, CMenu::DestroyMenu, CMenu::LoadMenulndirect, 
::LoadMenu. 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CMenu::LoadMenulndirect 
BOOL LoadMenulndirect( const BYTE FAR* /pMenuTemplate ); 


lpMenuTemplate 
Points to a menu template (which is a single 
MENUITEMTEMPLATEHEADER structure and a collection 
of one or more MENUITEMTEMPLATE structures). 


The MENUITEMTEMPLATEHEADER structure has the following generic 
form: 


typedef struct { 
WORD versionNumber; 
WORD offset; 

} MENUITEMTEMPLATEHEADER; 


The MENUITEMTEMPLATE structure has the following generic form: 


typedef struct { 
WORD mtOption; 
WORD mtID; 
char mtString; 
} MENUITEMTEMPLATEL1]; 


Loads a resource from a menu template in memory and attaches it to the CMenu 
object. A menu template is a header followed by a collection of one or more 
MENUITEMTEMPLATE structures, each of which may contain one or more 
menu items and pop-up menus. 


The version number should be 0. 


The mtOption flags should include MF_END for the last item in a pop-up list and 
for the last item in the main list. See AppendMenu for other flags. The mt/d mem- 
ber must be omitted from the MENUITEMTEMPLATE structure when 
MF_POPUP is specified in mtOption. 


The space allocated for the MENUITEMTEMPLATE structure must be large 
enough for mtString to contain the name of the menu item as a null-terminated 
string. 


TRUE if the menu resource was loaded successfully; otherwise FALSE. 


CMenu::DestroyMenu, CMenu::LoadMenu, ::LoadMenuIndirect 
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CMenu::ModifyMenu 


Syntax BOOL ModifyMenu( UINT nPosition, UINT nFlags, UINT nIDNewItem = 0, 
const char FAR* [pNewItem = NULL); 


BOOL ModifyMenu( UINT nPosition, UINT nFlags, UINT nIDNewItem, 
const CBitmap* pBmp); 


Parameters nPosition 
Specifies the menu item to be changed. The interpretation of nPosition depends 
on the setting of nFlags as shown in the following list: 


nFlags Interpretation of nPosition 


MF_BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This is the default 
if neither MF_ BYCOMMAND nor 
MF_BYPOSITION is set. 


MF_BYPOSITION Specifies that the parameter gives the position of 
the existing menu item (the first item is at 
position Q). 


nFlags 
Specifies how nPosition is interpreted and gives information about the changes 
to be made to the menu item. For a list of flags that may be set, see the 
AppendMenu member function. 


nlDNewltem 
Specifies either the command ID of the modified menu item or, if nFlags is set 
to MF_ POPUP, the menu handle (HMENU) of a pop-up menu. The 
nIDNewlItem parameter is ignored (not needed) if nFlags is set to 
MF_SEPARATOR. 


[pNewItem | 
Specifies the content of the new menu item. The interpretation of IpNewltem 
depends on the setting of nFlags as shown below: 


Remarks 


Return Value 


See Also 
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nFlags Interpretation of IpNewItem 


MF_OWNERDRAW Contains an application-supplied 32-bit value that 
the application can use to maintain additional 
data associated with the menu item. This 32-bit 
value is available to the application when it 
processes MF_MEASUREITEM and 
MF_DRAWITEM. 


MF_STRING Contains a long pointer to a null-terminated 
string or to a CString. 


The [pNewItem parameter is ignored (not needed) if nFlags is set to 
MF_SEPARATOR. 


pBmp 
Points to a CBitmap object that will be used as the menu item. 


Changes an existing menu item at the position specified by nPosition. The applica- 
tion specifies the new state of the menu item by setting values in nFlags. If this 
function replaces a pop-up menu associated with the menu item, it destroys the old 
pop-up menu and frees the memory used by the pop-up menu. 


When n/DNewltem specifies a pop-up menu, it becomes part of the menu in which 
it is inserted. If that menu is destroyed, the inserted menu will also be destroyed. 
An inserted menu should be detached from a CMenu object to avoid conflict. 


Whenever a menu that resides in a window is changed (whether or not the window 
is displayed), the application should call CWnd::DrawMenuBar. To change the 
attributes of existing menu items, it is much faster to use the CheckMenulItem 
and EnableMenultem functions. 


TRUE if the function is successful; otherwise FALSE. 


CMenu::AppendMenu, CMenu::InsertMenu, CMenu::CheckMenultem, 
CWnd::DrawMenuBar, CMenu::EnableMenultem, 
CMenu::SetMenultemBitmaps, CMenu::Detach, CMenu::~CMenu, 
::ModifyMenu 
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syntax 


Parameters 


Remarks 


Return Value 


See Also 


CMenu::RemoveMenu 
BOOL RemoveMenu( UINT nPosition, UINT nFlags ); 


nPosition 
Specifies the menu item to be removed. The interpretation of nPosition depends 
on the setting of nFlags as shown in the following list: 


nFlags Interpretation of nPosition 


MF_BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This 1s the default 
if neither MF_BYCOMMAND nor 
MF_BYPOSITION is set. 


MF_BYPOSITION Specifies that the parameter gives the position of 
the existing menu item (the first item is at 
position 0). 


nFlags 
Specifies how nPosition is interpreted. 


Deletes a menu item with an associated pop-up menu from the menu. It does not 
destroy the handle for a pop-up menu, allowing the menu to be reused. Before 
calling this function, the application may call GetSubMenu to retrieve the pop-up 
CMenu object for reuse. 


Whenever a menu that resides in a window is changed (whether or not the window 
is displayed), the application must call CWnd::DrawMenuBar. 


TRUE if the function is successful; otherwise FALSE. 


CWnd::DrawMenuBar, CMenu::GetSubMenu, ::RemoveMenu 


Syntax 


Parameters 


Remarks 
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CMenu::SetMenultemBitmaps 


BOOL SetMenultemBitmaps( UINT nPosition, UINT nFlags, 
const CBitmap* pBmp Unchecked, const CBitmap* pBmpChecked); 


nPosition 
Specifies the menu item to be changed. The interpretation of nPosition depends 
on the setting of nFlags as shown in the following list: 


nFlags Interpretation of nPosition 


MF_BYCOMMAND __ Specifies that the parameter gives the command 
ID of the existing menu item. This is the default 
if neither MF_ BY COMMAND nor 
MF_BYPOSITION is set. 


MF_BYPOSITION Specifies that the parameter gives the position of 
the existing menu item (the first item 1s at 
position 0). 


nFlags 
Specifies how nPosition is interpreted. 


pBmp Unchecked 
Specifies the bitmap to use for menu items that are not checked. 


pBmpChecked 
Specifies the bitmap to use for menu items that are checked. 


Associates the specified bitmaps with a menu item. Whether the menu item is 
checked or unchecked, Windows displays the appropriate bitmap next to the menu 
item. 


If either pBmpUnchecked or pBmpChecked is NULL, then Windows displays 
nothing next to the menu item for the corresponding attribute. If both parameters 
are NULL, Windows uses the default check mark when the item is checked and re- 
moves the check mark when the item is unchecked. When the menu is destroyed, 
these bitmaps are not destroyed. It is the responsibility of the application to de- 
stroy them. 
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Return Value 


See Also 


Syntax 


Parameters 


The Windows ::GetMenuCheckMarkDimensions function retrieves the dimen- 
sions of the default check mark used for menu items. The application uses these 
values to determine the appropriate size for the bitmaps supplied with this func- 
tion. Get the size, create your bitmaps, then set them. 


TRUE if the function is successful; otherwise FALSE. 


:;GetMenuCheckMarkDimensions, ::SetMenulItemBitmaps 


CMenu::TrackPopupMenu 


BOOL TrackPopupMenu( UINT nFlags, int x, int y, const CWnd* pWnd, 
LPRECT I[pRectReserved = 0); 


nFlags 
Specifies a screen-position flag and a mouse-button flag. The screen-position 
flag can be one of the following: 


Value _ Meaning 


TPM_CENTERALIGN — Centers the pop-up menu horizontally relative 
to the coordinate specified by x. 


TPM_LEFTALIGN Positions the pop-up menu so that its left side 
is aligned with the coordinate specified by x. 


TPM_RIGHTALIGN Positions the pop-up menu so that its right side 
is aligned with the coordinate specified by x. 


The mouse-button flag can be one of the following: 


Value Meaning 
TPM_LEFTBUTTON — Causes the pop-up menu to track the left 
mouse button. 


TPM_RIGHTBUTTON — Causes the pop-up menu to track the right 
mouse button. 


Specifies the horizontal position in screen coordinates of the left side of the 
menu on the screen. 


Remarks 


Return Value 


See Also 


CMenu::TrackPopupMenu 437 


Specifies the vertical position in screen coordinates of the top of the menu on 
the screen. 


pWnd 


Identifies the window that owns the pop-up menu. This window receives all 
WM_COMMAND messages from the menu. 


lpRectReserved 
Points to a RECT structure or CPoint object that contains the screen coordi- 
nates of a rectangle within which the user can click without dismissing the pop- 
up menu. If this parameter is NULL, the pop-up menu is dismissed if the user 
clicks outside the pop-up menu. This must be NULL for Windows version 3.0. 


Displays a floating pop-up menu at the specified location and tracks the selection 
of items on the pop-up menu. A floating pop-up menu can appear anywhere on the 
screen. 


TRUE if the function is successful; otherwise FALSE. 


CMenu::CreatePopupMenu, CMenu::GetSubMenu, ::TrackPopupMenu 
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class CMetaFileDC : public CDC 


A Windows metafile contains a sequence of GDI com- 
mands that can be replayed to create a desired image 
or text. 


To implement a Windows metafile, first create a 
CMetaFileDC object. 


You create a CMetaFileDC in two steps. First, call the constructor CMetaFileDC 
to construct the CMetaFileDC object, then call the Create member function, 


which creates a Windows metafile device context and attaches it to the 
CMetaFileDC object. 


After the CMetaFileDC object is created, send a sequence of CDC GDI com- 
mands to the metafile device context. Use only those GDI commands that create 
output, such as MoveTo and LineTo. 


Then call the Close member function, which closes the metafile device context 
and returns a metafile handle. Use the CMetaFileDC destructor to destroy the 
CMetaFileDC object. 


CDC::PlayMetaFile can then use the metafile handle to play the metafile re- 
peatedly, and the metafile can also be manipulated by Windows functions such as 
CopyMetaFile, which copies a metafile to disk. 


When the metafile is no longer needed, delete it from memory with the 
DeleteMetaFile Windows function. 


See Also CDC 


Public Members 


Construction/Destruction 


CMetaFileDC Constructs a CMetaFileDC object. 
Initialization 
Create Creates the Windows metafile device context and 


attaches it to the CMetaFileDC object. 
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Operations 

Close Closes the device context, and creates a metafile 
handle. 

SelectObject Selects a GDI drawing object into the specified 
device context, which replaces the previous object 
of the same type. 

SelectStockObject Retrieves one of the predefined stock pens, 


brushes, or fonts and causes the stock object to be- 
come the currently selected object of its type. 
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Member Functions 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


CMetaFileDC::Close 


HANDLE CloseQ); 


Closes the metafile device context and creates a Windows metafile handle that can 
be used to play the metafile by using the CDC::PlayMetaFile function and also 
used to manipulate the metafile with Windows functions such as CopyMetaFile. 


The metafile should be deleted after use by calling the Windows DeleteMetaFile 
function. 


A valid HANDLE to a metafile if the function is successful. Otherwise, it is 
NULL. 


CDC::PlayMetaFile, ::CloseMetaFile, ::GetMetaFileBits, ::CopyMetaFile, 
::DeleteMetaFile 


CMetaFileDC::CMetaFileDC 


CMetaFileDCQ; 
Construction of a CMetaFileDC object is a two-step process. First, call 
CMetaFileDC, then call Create, which creates the Windows metafile device con- 


text and attaches it to the CMetaFileDC object. 


CMetaFileDC::Create 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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CMetaFileDC::Create 


BOOL Create(const char FAR* /pFilename = NULL ); 


lpFilename 
Points to a null-terminated character string. Names an existing metafile on disk 
to load. If JpFilename is NULL, a new in-memory metafile is created. 


You construct a CMetaFileDC object in two steps. First, call the constructor 
CMetaFileDC, then call Create, which creates the Windows metafile device con- 
text and attaches it to the CMetaFileDC object. 


TRUE if the function is successful; otherwise FALSE. 


CMetaFileDC::CMetaFileDC, ::CreateMetaFile 


CMetaFileDC::SelectObject 


BOOL SelectObject( CGdiObject* pObject ); 


pObject 
Identifies the object to be selected into the CMetaFileDC. The selected object 
can be one of the following: 


CBitmap 
CBrush 
CFont 
CPen 
CRegn 
CPalette 


Selects an object into the CMetaFileDC. 


CMetaFileDC performs its own object cleanup, so an application does not have to 
reselect default objects when recording a metafile. 
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Return Value 


See Also 


syntax 


Parameters 


Remarks 
Return Value 


See Also 


TRUE if the function is successful; otherwise FALSE. 


CGdiObject::DeleteObject, CDC::SelectClipRgn, CDC::SelectPalette, 
::SelectObject 


CMetaFileDC::SelectStockObject 


BOOL SelectStockObject( int nindex ); 

nIndex 
Specifies the type of stock object desired. See CDC::SelectObject for a list of 
the possible stock objects. | 

Selects one of the predefined stock pens, brushes, or fonts into the CMetaFileDC. 


TRUE if the function is successful; otherwise FALSE. 


CDC::SelectStockObject 
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class CModalDialog : public CDialog 


The CModaIDialog class provides modal CObject 
dialog boxes. In this type of dialog box, the er 


user must respond before any processing out- 
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Except in the most trivial cases, such as an CModaiDialog eat 


About dialog box, you must derive your own 
modal dialog class from CModalDialog. 


In your derived class, you can add member variables and member functions to 
specify the behavior of the dialog box. Add member variables to store data entered 
by the user via the dialog box controls or to store data for display through the con- 
trols. Add member functions to set and get this data. Add message-handler mem- 
ber functions to process messages for the controls in the dialog box. 


Like other classes derived from class CWnd, classes derived from CModalIDialog 
need their own message maps. If you declare any message-handler member func- 
tions, you must also provide a message map that connects the Windows messages 
with your handlers. 


Note The three most common functions, OnInitDialog, OnOK, and OnCancel, 
do not need message-map entries. 


Create a modal dialog object by constructing it. To do this, create a dialog object 
using the CModalDialog constructor, as shown in the example below. 


Once the dialog object has been constructed, call its DoModal member function to 
run the dialog box. For example, to construct a modal dialog object of class 
CMyModal and run the dialog box, use the following coding: 


CMyModal myModalDlg; 
myModalDlg.DoModal(); 


When the user clicks one of the dialog-box push buttons, such as OK or Cancel, 
the dialog box closes and it is removed from the screen. 


After the user closes the dialog box, its member variables are accessed through the 
member functions that you defined to get information entered by the user. 


For example, for a modal dialog box that has an editable text control, you can 
override the OnOK message-handler function in your derived modal dialog 

class so that when the user clicks the OK button, OnOK retrieves the text entered 
in the control and stores it in a data member of the dialog object. Later, after 
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DoModal returns, you can call a member function of the dialog object to retrieve 
the stored text. 


You are responsible for supplying the member variables and member functions 
needed to access the dialog’s data. Declare them in the class you derive from 
CModalDialog. 


CDialog::EndDialog is called automatically in OnOK and OnCancel when the 
user closes the dialog box. 


If the dialog box requires some initialization, override the CDialog::OnInitDialog 
member function to perform the initialization. For example, if an edit field in the 
dialog box is to display a default value that the user can accept or replace, override 
OnlnitDialog to initialize the default text in the edit field. OnInitDialog is called 
automatically while the dialog is being created before the dialog box appears on 
the screen. 


See Also CModalDialog::DoModal, CDialog::EndDialog, CWnd::MessageBox, 
CModalDialog::OnOK, CModalDialog::OnCancel, WM_INITDIALOG, 
WM_CLOSE, WM_SETFONT 


Public Members 


Construction/Destruction 


CModalDialog Constructs a CModalDialog object and stores the 
parameters for use when the member function 
DoModal is called. 


Initialization 


CreateIndirect Initializes a CModalDialog object as the second 
phase of indirect dialog-box creation (nonresource 
based). The parameters are stored until the func- 
tion DoModal is called. 


Operations 
DoModal Invokes the dialog box and returns when done. 


Overridables 
OnOK 


OnCancel 
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Override this member to perform the OK button 
action. The default terminates the dialog box, and 
DoModal will return IDOK. 


Override this member to perform the Cancel but- 
ton action. The default terminates the dialog box, 
and DoModal will return IDCANCEL. 
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Member Functions 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


CModalDialog::CModalDialog 


CModalDialog( const char FAR* /[pTemplateName, 
CWnd* pParentWnd = NULL ); 


CModalDialog( UINT n/DTemplate, CWnd* pParentWnd = NULL ); 


lpTemplateName 
Contains a string that is the name of a dialog-box resource template. 


pParentWnd 
Points to the parent window object (of type CWnd) of the dialog object. If it is 
NULL, the dialog object’s parent window is set to the main application win- 
dow, as shown in the following code: 


if( pParentWnd == NULL ) 
pParentWnd = AfxGetApp( )->m_pMainWnd; 


nIDTemplate 
Contains a dialog resource template ID number. 


Provides two public constructors, with different argument signatures, to permit the 
construction of CModalDialog objects directly or from resource templates. 


When you construct the dialog object to be used with CreateIndirect, pass 
NULL for the first parameter because there is no resource file template to be used 
in this case. 


CModalDialog::CreateIndirect 


CModalDialog::Createlndirect 
BOOL CreateIndirect( HANDLE hDialogTemplate ); 


hDialogTemplate 
Contains a resource handle to global memory containing a dialog-box resource 
template. The template data structure is of type DLGTEMPLATHE, which iden- 
tifies the block of memory used as a dialog-box template. 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 
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This member function uses a dialog resource constructed in memory to initialize a 
modal dialog object. The resource has the form of a DLGTEMPLATE structure. 
For more information on this structure, see the Windows Software Development 
Kit documentation. 


To create a modal dialog indirectly, first create a DLGTEMPLATE structure in 
memory and retain a HANDLE to it. Then call the CModalDialog constructor to 
construct the dialog object. In this case, pass NULL for the first parameter to the 
constructor. Next, call CreateIndirect to store your handle to the in-memory 
dialog template. The Windows dialog is created and displayed later, when the 
DoModal member function runs. 


TRUE if the dialog object was created and initialized successfully; otherwise 
FALSE. 


WML_INITDIALOG, DS_SETFONT, DLGTEMPLATE, 
CWnd::Destroy Window, CModalDialog::CModalDialog 


CModalDialog::DoModal 


int DoModalQ); 


Invokes the dialog box and returns the dialog box result when done. This member 
function handles all interaction with the user while the dialog box is active. This is 
what makes the dialog box modal; that is, the user cannot interact with other win- 
dows until the dialog box is closed. 


If the user clicks one of the push buttons in the dialog box, such as OK or Cancel, 
a message-handler member function, such as OnOK or OnCancel, is called to 
attempt to close the dialog box. The default OnOK and OnCancel member func- 
tions will end the dialog with results IDOK and IDCANCEL, respectively. You 
can override these message-handler functions to alter this behavior. 


An int value that specifies the value of the nResult parameter that was passed to 
the EndDialog member function, which is used to terminate the dialog box.The 
return value is —1 if the function could not create the dialog box. 


::DialogBox 
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syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


CModalDialog::OnCancel 


CModalDialog::O0nCancel 


virtual void OnCancel(); 


Override this member function to perform Cancel button action. The default 
simply terminates the dialog box and causes DoModal to return IDCANCEL. 


CModalDialog::OnOK, WM_COMMAND 


CModalDialog::0n0K 


virtual void OnOKO; 


Override this member function to perform OK button action. The default simply 
terminates the dialog box and causes DoModal to return IDOK. _ 


CModalDialog::OnCancel, WM_COMMAND 
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class CNotSupportedException : public CException 


A CNotSupportedException object represents 
an exception that is the result of a request for an 
unsupported feature. No further qualification is 
necessary or possible. 


#include <afx.h> 


Public Members 
CNotSupportedException Constructs a CNotSupportedException object. 


Member Functions 


CNotSupportedException 
‘:CNotSupportedException 
Syntax CNotSupportedException(; 


Remarks Constructs a CNotSupportedException object. 


Do not use this constructor directly, but rather call the global function 
AfxThrowNotSupportedException. 


See Also Chapter 5, “Exception Processing,” AfxThrowNotSupportedException 
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class CObArray : public CObject 


See Also 


Derivation 


The CObArray class supports arrays of CObject 
pointers. These object arrays are similar to C arrays, 
but they can dynamically shrink and grow as 
necessary. 


Array indexes always start at position 0. You can decide whether to fix the upper 
bound or allow the array to expand when you add elements past the current bound. 
Memory is allocated contiguously to the upper bound, even if some elements 

are null. 


The elements of a CObArray object must fit in one 64K segment together with ap- 
proximately 100 allocation overhead bytes. If CObject pointers are 16-bit near 
pointers (as they are in the small and medium memory models), then an array size 
limit is about 32,000 elements, but because there is only one data segment, the ob- 
jects themselves will probably exhaust memory before the array does. If CObject 
pointers are 32-bit far pointers (as they are in the compact and large memory mod- 
els), then an array size limit is about 16,000 elements. 


As with a C array, the access time for a CObArray indexed element is constant 
and is independent of the array size. 


CObArray incorporates the IMPLEMENT_SERIAL macro to support serializa- 
tion and dumping of its elements. If an array of CObject pointers is stored to an ar- 
chive, either with the overloaded insertion operator or with the Serialize member 
function, each CObject element is, in turn, serialized along with its array index. 


If you need a dump of individual CObject elements in an array, you must set the 
depth of the CDumpContext object to | or greater. 


When a CODArray object is deleted, or when its elements are removed, only the 
CObject pointers are removed, not the objects they reference. 


#include <afxcoll.h> 
CStringArray, CPtrArray, CByteArray, CWordArray, CDWordArray 


Array class derivation is similar to list derivation. For details on the derivation of a 
special-purpose list class, see the tutorial in the Class Library User’s Guide. 


Note You must use the IMPLEMENT_SERIAL macro in the implementation of 
your derived class if you intend to serialize the array. 


Public Members 


Construction/Destruction 


CObArray 
~CObArray 


Bounds 
GetSize 
GetUpperBound 
SetSize 


Operations 
FreeExtra 


RemoveAll 


Element Access 
GetAt 
SetAt 


ElementAt 


Growing the Array 
SetAtGrow 


Add 
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Constructs an empty array for CObject pointers. 


Destroys a CObArray object. 


Gets the number of elements in this array. 
Returns the largest valid index. 


Sets the number of elements to be contained in this 
array. 


Frees all unused memory above the current upper 
bound. 


Removes all the elements from this array. 


Returns the value at a given index. 


Sets the value for a given index; array not allowed 
to grow. 


Returns a temporary reference to the element 
pointer within the array. 


Sets the value for a given index; grows the array if 
necessary. 


Adds an element to the end of the array; grows the 
array if necessary. 


452 


CObArray 


Insertion/Removal 
InsertAt 


RemoveAt 


Operators 
operator [ | 


Inserts an element (or all the elements in another 
array) at a specified index. 


Removes an element at a specific index. 


Sets or gets the element at the specified index. 
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Member Functions 
CObArray::Add 
Syntax int Add( CObject®* newElement ) 


throw( CMemoryException ); 


Parameters newElement 
The CObject pointer to be added to this array. 


Remarks Adds a new element to the end of an array, growing the array by 1. If SetSize has 
been used with an nGrowBy value greater than 1, then extra memory may be allo- 
cated. However the upper bound will increase by only 1. 


Return Value The index of the added element. 


Example CObArray array; 


array.Add( new CAge( 21 ) ); // Element Q 

array.Add( new CAge( 4@ ) ); // Element 1 
dFifdef DEBUG 

afxDump.SetDepth( 1 ); 

afxDump << "Add example: " << &array << "\\n"; 
dtendi f 


The results from this program are as follows: 


Add example: A CObArray with 2 elements 


[@] = a CAge at $442A 21 
[1] = a CAge at $4468 40 
See Also CObArray::SetAt, CObArray::SetAtGrow, CObArray::InsertAt, 


CObArray::operator [ | 
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Syntax 


Remarks 


Example 


See Also 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 


CObArray::CObArray 


CObArray(Q); 


Constructs an empty CObject pointer array. The array grows one element at a 
time. 


See the CObList constructor for a listing of the CAge class used in all collection ex- 
amples. 


CObArray array; // Array on the stack 


CObArray* parray = new CObArray; // Array on the heap 


CObList constructor 


CObArray::~CObArray 


~CObArray(); 


Destroys a CObArray object but does not destroy the CObject objects that are 
referenced in the array. 


CObArray::ElementAt 


CObject* & ElementAt( int nJndex ); 


nIndex 


An integer index that is greater than or equal to 0 and less than or equal to 
GetUpperBound(). 


Returns a temporary reference to the element pointer within the array. It is used to 
implement the left-side assignment operator for arrays. 


Note This is an advanced function that should be used only to implement special 
array operators. 


Return Value 


See Also 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 
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A reference to a CObject pointer. 


CObArray::operator [ ] 


CObArray::FreeExtra 


void FreeExtra(); 


Frees any extra memory that was allocated while the array was grown. This func- 
tion has no effect on the size or upper bound of the array. 


CObArray::GetAt 


CObject* GetAt( int nJndex ) const; 


nIndex 
An integer index that is greater than or equal to 0 and less than or equal to 
GetUpperBound(). 


Returns the array element at the specified index. 


The CObject pointer element currently at this index; NULL if no element is 
stored at the index. 


CObArray array; 
array.Add( new CAge( 21 ) ); // Element @ 


array.Add( new CAge( 4@ ) ); // Element 1 
ASSERT( *(CAge*) array.GetAt( @ ) == CAge( 21 ) ); 


CObArray::SetAt, CObArray::operator [ ] 
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Syntax 


Remarks 


See Also 


Syntax 


Remarks 


Example 


See Also 


Syntax 


CObArray::GetSize 


CObArray::GetSize 


int GetSize() const; 


Returns the size of the array. Since indexes are zero-based, the size is | greater 
than the largest index. 


CObArray::GetUpperBound, CObArray::SetSize 


CObArray::GetUpperBound 


int GetUpperBound() const; 


Returns the current upper bound of this array. Because array indexes are zero- 
based, this function returns a value 1 less than GetSize. 


The condition GetUpperBound() = —1 indicates that the array contains no ele- 
ments. 


CObArray array; 
array.Add( new CAge( 21 ) ); // Element @ 


array.Add( new CAge( 40 ) ); // Element 1 
ASSERT( array.GetUpperBound() == 1 ); // Largest index 


CObArray::GetSize, CObArray::SetSize 


CObArray::InsertAt 


void InsertAt( int n/ndex, CObject* newElement, int nCount = 1 ) 
throw( CMemoryException ); 


void InsertAt( int nStartIndex, CObArray* pNewArray ) 
throw( CMemoryException ); 


Parameters 


Remarks 


Example 


See Also 
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nIndex 
An integer index that may be greater than GetUpperBound(). 


newElement 
The CObject pointer to be placed in this array. A newElement of value NULL 
is allowed. 


nCount 
The number of times this element should be inserted (defaults to 1). 


nStartIndex 
An integer index that may be greater than GetUpperBound(). 


pNewaArray 
Another array that contains elements to be added to this array. 


The first version of InsertAt inserts one element (or multiple copies of an ele- 
ment) at a specified index in an array. In the process, it shifts up (by incrementing 
the index) the existing element at this index, and it shifts up all the elements 

above it. 


The second version inserts all the elements from another CObArray collection, 
starting at the nStartIndex position. 


The SetAt function, in contrast, replaces one specified array element and does not 
shift any elements. 


CObArray array; 


array.Add( new CAge( 21 ) ); // Element Q 

array.Add( new CAge( 40 ) ); // Element 1 (will become 2) 

array.InsertAt( 1, new CAge( 30 ) ); // New element 1 
d:ifdef _ DEBUG 

afxDump.SetDepth( 1 ); 

afxDump << "InsertAt example: " << &array << "\\n"; 
dkendi f 


The results from this program are as follows: 


InsertAt example: A CObArray with 3 elements 


[@] = a CAge at $45C8 21 
[1] = a CAge at $4646 30 
[2] = a CAge at $4606 40 


CObArray::SetAt, CObArray::RemoveAt 
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Syntax 


Remarks 


Example 


Syntax 


Parameters 


Remarks 


CObArray::RemoveAll 


void RemoveAllQ; 


Removes all the pointers from this array but does not actually delete the CObject 
objects. If the array is empty already, the function still works. 


The RemoveAll function frees all memory used for pointer storage. 


CObArray array; 
CAgex* pal; 
CAge* pa2; 


array.Add( pal new CAge( 21 ) ); // Element @ 

array.Add( pa2 = new CAge( 4@ ) ); // Element 1 

ASSERT( array.GetSize() == 2 ); 

array.RemoveAl|l(); // Pointers removed but objects not deleted 
ASSERT( array.GetSize() == @ ); 

delete pal; 

delete pa2; // Cleans up memory 


CObArray::RemoveAt 


void RemoveAt( int n/ndex, int nCount = 1 ); 


nIndex 
An integer index that is greater than or equal to 0 and less than or equal to 
GetUpperBound(). 


nCount 
The number of elements to remove. 


Removes one or more elements starting at a specified index in an array. In the 
process, it shifts down all the elements above the removed element(s). It decre- 
ments the upper bound of the array but does not free memory. 


If you try to remove more elements than are contained in the array above the re- 
moval point, then the Debug version of the library asserts. 


The RemoveAt function removes the CObject pointer from the array, but it does 
not delete the object itself. 


Example 


See Also 


Syntax 


Parameters 


Remarks 


CObArray::SetAt 


CObArray array; 
CObject* pa; 


array.Add( new CAge( 21 ) ); // Element @ 
array.Add( new CAge( 40 ) ); // Element 1 
if( ( pa = array.GetAt( @® ) ) != NULL ) 
{ 
array.RemoveAt( @ ); // Element 1 moves to @ 
delete pa; // Delete the original element at @ 
} 
dFifdef _ DEBUG 
afxDump.SetDepth( 1 ); 
afxDump << “RemoveAt example: " << &array << "\\n"; 
dtendi f 


The results from this program are as follows: 


RemoveAt example: A CObArray with 1 elements 
[Q@] = a CAge at $4606 40 


CObArray::SetAt, CObArray::SetAtGrow, CObArray::InsertAt 


CObArray::SetAt 


void SetAt( int n/ndex, CObject* newElement ); 


nIndex 


An integer index that is greater than or equal to 0 and less than or equal to 


GetUpperBound(). 


newElement 
The object pointer to be inserted in this array. A NULL value is allowed. 


Sets the array element at the specified index. SetAt will not cause the array to 


grow. Use SetAtGrow if you want the array to grow automatically. 
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You must ensure that your index value represents a valid position in the array. If it 


is out of bounds, then the Debug version of the library asserts. 
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Example CObArray array; 
CObject* pa; 


array.Add( new CAge( 21 ) ); // Element @ 
array.Add( new CAge( 4@ ) ); // Element 1 
if( ( pa = array.GetAt( @ ) ) != NULL ) 
{ 
array.SetAt( @, new CAge( 30 ) ); // Replace element @ 
delete pa; // Delete the original element at Q 
} 
dFHifdef _ DEBUG 
afxDump.SetDepth( 1 ); 
afxDump << "SetAt example: " << &array << "\\n"; 
dtendif 


The results from this program are as follows: 


SetAt example: A CObArray with 2 elements 
[@] = a CAge at $47E@ 30 
[1] = a CAge at $47A@ 4@ 


See Also CObArray::GetAt, CObArray::SetAtGrow, CObArray::ElementAt, 
CObArray::operator [ | 


CObArray::SetAtGrow 


Syntax void SetAtGrow( int n/ndex, CObject* newElement ) 
throw( CMemoryException ); 


Parameters nIndex 
An integer index that is greater than or equal to 0. 


newElement 
The object pointer to be added to this array. A NULL value is allowed. 


Remarks Sets the array element at the specified index. The array grows automatically if nec- 
essary (that is, the upper bound is adjusted to accommodate the new element). 


Example 


See Also 


Syntax 


Parameters 


Remarks 
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CObArray array; 


array.Add( new CAge( 21 ) ); // Element @ 
array.Add( new CAge( 4@ ) ); // Element 1 
array.SetAtGrow( 3, new CAge( 65 ) ); // Element 2 deliberately 
// skipped 
#ifdef _ DEBUG 
afxDump.SetDepth( 1 ); 
afxDump << "SetAtGrow example: " << &array << "\\n"; 
dtendi f 


The results from this program are as follows: 


SetAtGrow example: A CObArray with 4 elements 


[@] = a CAge at $4/7C@ 21 
[1] = a CAge at $4800 40 
[2] = NULL 

[3] = a CAge at $4840 65 


CObArray::GetAt, CObArray::SetAt, CObArray::ElementAt, 
CObArray::operator [ | 


CObArray::SetSize 


void SetSize( int nNewSize, int nGrowBy = -1 ) 
throw( CMemoryException ); 


nNewSize 
The new array size (number of elements). Must be greater than or equal to 0. 


nGrowBy 
The minimum number of element slots to allocate if a size increase is necessary. 


Establishes the size of an empty or existing array; allocates memory if necessary. 


If the new size is smaller than the old size, then the array is truncated and all un- 
used memory is released. 


The nGrowBy parameter affects internal memory allocation while the array is 
growing. Its use never affects the array size as reported by GetSize and 
GetUpperBound. 


462. CObArray::operator [ ] 


Operators 


syntax 


Remarks 


Example 


See Also 


CObArray::operator [ ] 


CObject*& operator [ ]( int n/ndex ); 


CObject* operator [ ]( int n/ndex ) const; 


These subscript operators are a convenient substitute for the SetAt and GetAt 
functions. 


The first operator, invoked for arrays that are not const, may be used on either the 
right (r-value) or the left (I-value) of an assignment statement. The second, in- 
voked for const arrays, may be used only on the right. 


The Debug version of the library asserts if the subscript (either on the left or right 
side of an assignment statement) is out of bounds. 


CObArray array; 
CAge* pa; 


array.Add( new CAge( 21 ) ); // Element @ 

array.Add( new CAge( 4@ ) ); // Element 1 

pa = (CAgex)array[@]; // Get element @ 

ASSERT( *pa == CAge( 21 ) ); // Get element @ 

array[@] = new CAge( 30 ); // Replace element Q 

delete pa; 

ASSERT( *(CAge*) array[@] == CAge( 30 ) ); // Get new element @ 


CObArray::GetAt, CObArray::SetAt 
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class CObject 


Derivation 


CObject is the principal base class for the Microsoft Foundation Class Library. It 
serves as the root not only for library classes such as CFile and CObList, but also 
for the classes that you write. CObject provides basic services, including: 


= Serialization support 
= Run-time class information 
= Object diagnostic output 


=" Compatibility with collection classes 
Refer to Part 1 for a detailed description of these features. 


Note CObject does not support multiple inheritance. Your derived classes can 
have only one CObject base class, and that CObject must be leftmost in the hier- 
archy. It is permissible, though, to have structures and non-CObject-derived 
classes in right-hand multiple-inheritance branches. 


#include <afx.h> 
You will realize major benefits from CObject derivation if you use some of the 
optional macros in your class implementation and declarations. 


The first-level macros, DECLARE_ DYNAMIC and 
IMPLEMENT_DYNAMIC, permit run-time access to the class name and its 
position in the hierarchy. This, in turn, allows meaningful diagnostic dumping. 


The second-level macros, DECLARE_SERIAL and IMPLEMENT_SERIAL, 
include all the functionality of the first-level macros, and they enable an object to 
be serialized to and from an archive. 


For important information about deriving Microsoft Foundation classes and C++ 
classes in general, see “How to Derive a Class from CObject” in Chapter 8 of the 
Class Libraries User’s Guide. 
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Public Members 


Construction/Destruction 
~CObject 
operator new 


operator delete 


Diagnostics 
AssertValid 
Dump 


Serialization 
IsSerializable 


Serialize 


Miscellaneous 
GetRuntimeClass 


IsKindOf 


Construct 


Protected Members 
CObject 


Private Members 
CObject 


operator = 


Virtual destructor. 
Special new operator. 


Special delete operator. 


Validates this object’s integrity. 


Produces a diagnostic dump of this object. 


Tests to see if this object can be serialized. 


Loads or stores an object from/to an archive. 


Returns the CRuntimeClass structure correspond- — 
ing to this object’s class. 


Tests this object’s relationship to a given class. 


An internal function that must be public—do 
not use. 


Default constructor. 


Copy constructor. 


Assignment operator. 


Macros 


RUNTIME_CLASS 


DECLARE_DYNAMIC 


IMPLEMENT_ DYNAMIC 


DECLAR_ SERIAL 


IMPLEMENT_SERIAL 


CObject 


Returns the CRuntimeClass 
structure corresponding to the 
named class. 


Permits access to run-time class 
information (used in each class 
declaration). 


Permits access to run-time class 
information (used once in the class 
implementation). 


Permits serialization and access to 
run-time class information (used in 
each class declaration). 


Permits serialization and access to 
run-time class information (used 
once in the class implementation). 
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CObject::AssertValid 


Member Functions and Macros 


Syntax 


Remarks 


Example 


CObject::AssertValid 


virtual void Assert Valid() const; 


AssertValid performs a validity check on this object by checking its internal state. 
In the Debug version of the library, AssertValid may assert and thus terminate the 
program with a message that lists the line number and filename where the asser- 
tion failed. 


When you write your own class, you should override the AssertValid function to 
provide diagnostic services for yourself and other users of your class. The overrid- 
den AssertValid usually calls the Assert Valid function of its base class pope 
checking data members unique to the derived class. 


Because AssertValid is a const function, you are not permitted to change the ob- 
ject state during the test. Your own derived class Assert Valid functions should not 
throw exceptions but rather should assert if they detect invalid object data. 


The definition of “validity” depends on the object’s class. As a rule, the function 
should perform a “shallow check.” That is, if an object contains pointers to other 
objects, it should check to see if the pointers are not null, but should not perform 
validity testing on the objects referred to by the pointers. 


See CODbList:: CObList for a listing of the CAge class used in all CObject 
examples. 


void CAge::AssertValid() const 
{ 
CObject::AssertValid(); 
ASSERT( ( m_years > @ ) && ( m_years < 105 ) ); 


Syntax 


Parameters 


Remarks 


Syntax 


Remarks 
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CObject::CObject 


CObjectQ; 
CObject( const CObject& objectSrc ); 


objectSrc 
A reference to another CObject. 


These functions are the standard CObject constructors. The default version is auto- 
matically called by the constructor of your derived class. 


If your class is serializable (it incorporates the IMPLEMENT_SERIAL macro), 
then you must have a default constructor (a constructor with no arguments) in your 
class declaration. If you don’t need a default constructor, declare a private or pro- 
tected “empty” constructor. For more information, see “How to Derive a Class 
from CObject” in Chapter 8 of the Class Libraries User’s Guide. 


The standard C++ default class copy constructor does a member-by-member copy. 
The presence of the private CObject copy constructor guarantees a compiler error 
message if the copy constructor of your class is needed but not available. You 
must, therefore, provide a copy constructor if your class requires this capability. 


CObject::~CObject 
virtual ~CObject() 


This function 1s the standard CObject destructor. If your derived class must 

free allocated memory or do other cleanup work, you must provide your own 
destructor. Because ~CObject is a virtual destructor, C++ ensures that 
CObject::~CObject is automatically called as part of the destructor of your class. 


Note Your destructor should not throw exceptions or allocate objects. 


468 DECLARE_DYNAMIC Macro 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


- Parameters 


Remarks 


DECLARE_DYNAMIC Macro 


DECLARE_DYNAMIC( class_name ) 


class_name 
The actual name of the class (without quotes). 


DECLARE_DYNAMIC generates the C++ header code necessary for a 
CObject-derived class with accessible run-time information. Use the 
DECLARE_DYNAMIC macro in a .H module, then include that module in all 
-CPP modules that need access to objects of this class. For more information, see 
“How to Derive a Class from CObject” in Chapter 8 of the Class Libraries User’s 
Guide. 


~ If DECLARE_ DYNAMIC is included in the class declaration, then 


IMPLEMENT_DYNAMIC must be included in the class implementation. 


The DECLARE_SERIAL macro includes all the functionality of 
DECLARE_ DYNAMIC but adds the ability to serialize the object. 


DECLARE_SERIAL, IMPLEMENT_DYNAMIC 


DECLARE_ SERIAL Macro 


DECLARE_SERIAL( class_name ) 


class_name | 
The actual name of the class (without quotes). 


DECLARE_SERIAL generates the C++ header code necessary for a 
CObject-derived class that can be serialized. Use the DECLARE_SERIAL 
macro in a .H module, then include that module in all .CPP modules that need 
access to objects of this class. For more information, see “How to Derive a Class 
from CObject,” in Chapter 8 of the Class Libraries User’s Guide. 


See Also 


Syntax 


Parameters 


Remarks 


CObject::Dump 469 


If DECLARE_SERIAL is included in the class declaration, then 
IMPLEMENT_SERIAL must be included in the class implementation. 


The DECLARE_SERIAL macro includes all the functionality of 
DECLARE_DYNAMIC. 


DECLARE_DYNAMIC, IMPLEMENT_SERIAL 


CObject::Dump 


virtual void Dump( CDumpContext& dc ) const; 


dc 
The diagnostic dump context for dumping, usually afxDump. 


Dumps the contents of your object to a CDumpContext object. 


When you write your own class, you should override the Dump function to pro- 
vide diagnostic services for yourself and other users of your class. The overridden 
Dump usually calls the Dump function of its base class before printing data mem- 
bers unique to the derived class. CObject::Dump prints the class name if your 
class uses the IMPLEMENT_ DYNAMIC or IMPLEMENT_SERIAL macro. 


Note Your Dump function should not print a newline at the end of its output. 


Dump calls make sense only in the Debug version of the Microsoft Foundation 
library. Bracket calls, function declarations, and function implementations with 
#ifdef _DEBUG/#endif statements for conditional compilation. 


Since Dump is a const function, you are not permitted to change the object state 
during the dump. 


The CDumpContext operator << calls Dump when a CObject pointer is 
inserted. 
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Example 


Syntax 


Remarks 


Return Value 


Dump permits only “acyclic” dumping of objects. You can dump a list of objects, 
for example, but if one of the objects is the list itself, you will eventually overflow 
the stack. 


void CAge::Dump( CDumpContext &dc ) const 
{ 
CObject::Dump( dc ); 
dc << m_years; 


CObject::GetRuntimeClass 


virtual CRuntimeClass* GetRuntimeClass() const; 


There is one CRuntimeClass structure for each CObject-derived class. The struc- 
ture members are as follows: 


const char* m_pszClassName 
A null-terminated string containing the ASCII class name. 


int m_nObjectSize 
The actual size of the object. If the object has data members that point to allo- 
cated memory, the size of that memory is not included. 


WORD m_wSchema 
The schema number (—1 for nonserializable classes). See the 
IMPLEMENT_SERIAL macro for a description of schema number. 


void (*m_ pfnConstruct)(void* p) 
A pointer to the default constructor of your class (valid only if the class is 
serializable). 


CRuntimeClass* m_ pBaseClass 
A pointer to the CRuntimeClass structure that corresponds to the base class. 


This function requires use of the IMPLEMENT_ DYNAMIC or 
IMPLEMENT_SERIAL macros in the class implementation. You will get 
incorrect results otherwise. 


A pointer to the CRuntimeClass structure corresponding to this object’s class; 
never NULL. 


Example 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


IMPLEMENT_SERIAL Macro 


CAge a(2l1); 
CRuntimeClass* prt = a.GetRuntimeClass(); 
ASSERT( stremp( prt->m_pszClassName, “CAge" ) == @ ); 


CObject::IsKindOf, RUNTIME_ CLASS 


IMPLEMENT_DYNAMIC Macro 


IMPLEMENT_DYNAMIC( class_name, base_class_name ) 


class_name 
The actual name of the class (without quotes). 


base_class_name 
The name of the base class (without quotes). 


Generates the C++ code necessary for a dynamic CObject-derived class with 
run-time access to the class name and position within the hierarchy. Use the 
IMPLEMENT_DYNAMIC macro in a .CPP module, then link the resulting 
object code only once. For more information, see “How to Derive a Class from 
CObject,” in Chapter 8 of the Class Libraries User’s Guide. | 


IMPLEMENT_SERIAL 


IMPLEMENT_SERIAL Macro 


IMPLEMENT_SERIAL( class_name, base_class_name, wSchema ) 


class_name 
The actual name of the class (without quotes). 


base_class_name 
The name of the base class (without quotes). 


wSchema 
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Placeholder for future implementation. The class schema number must not be 


—|. This is a version number that will be encoded in the archive to enable a 
deserializing program to identify and handle data created by earlier program 
versions. 
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Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


Generates the C++ code necessary for a dynamic CObject-derived class with 
run-time access to the class name and position within the hierarchy. Use the 
IMPLEMENT_SERIAL macro in a .CPP module; then link the resulting object 
code only once. For more information, see “How to Derive a Class from CObject” 
in Chapter 8 of the Class Libraries User’s Guide. 


IMPLEMENT_DYNAMIC 


CObject::isKindOf 


BOOL IsKindOf( const CRuntimeClass* pClass ) const; 


pClass 
A pointer to a CRuntimeClass structure associated with your CObject-derived 
class. 


IsKindOf tests this object to see if (1) it is an object of the specified class or (2) if 
it is an object of a class derived from the specified class. This function only works 
for classes declared with the DECLARE_ DYNAMIC or DECLARE_ SERIAL 
macros. 


Do not use this function extensively because it defeats the C++ polymorphism 
feature. Use virtual functions instead. 


TRUE if the object corresponds to the class; otherwise FALSE. 


CAge a(21); // must use IMPLEMENT_DYNAMIC or IMPLEMENT_SERIAL 
ASSERT( a.IsKindOf( RUNTIME_CLASS( CAge ) ) ); 


CObject::GetRuntimeClass, RUNTIME_CLASS 


Syntax 


Remarks 


Return Value 


Example 


See Also 


Syntax 


Parameters 


Remarks 
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CObject::lsSerializable 
BOOL IsSerializable() const; 


IsSerializable tests whether this object is eligible for serialization. For a class to 
be serializable, its declaration must contain the DECLARE_SERIAL macro, and 
the implementation must contain the IMPLEMENT_SERIAL macro. 


Note Do not override this function. 
TRUE if this object can be serialized; otherwise FALSE. 


CAge a(21); 
ASSERT( a. IsSerializable() ); 


CObject::Serialize 


CObject::Serialize 


virtual void Serialize( CArchive& ar ) 
throw( CMemoryException, CArchiveException, CFileException ); 


ar 
A CArchive object to serialize to or from. 


Serialize reads or writes this object from or to an archive. 


You must override Serialize for each class that you intend to serialize. The over- 
ridden Serialize must first call the Serialize function of its base class. 


You must also use the DECLARE_SERIAL macro in your class declaration, and 
you must use the IMPLEMENT_SERIAL macro in the implementation. 


Use CArchive::IsLoading or CArchive::IsStoring to determine whether the ar- 
chive is loading or storing. 


Serialize is called by CArchive::ReadObject and CArchive:: WriteObject. 
These functions are associated with the CArchive insertion operator (<<) and ex- 
traction operator (>>). 


474 RUNTIME _CLASS Macro 


Example 


Syntax 


Parameters 


Remarks 


Example 


See Also 


For serialization examples, refer to both the cookbook and the tutorial in the Class 
Libraries User’s Guide. 


void CAge::Serialize( CArchive& ar ) 


{ 
CObject::Serialize( ar ); 
if( ar.IsStoring() ) 
ar << m_years; 
else 
ar >> m_years; 
iF 


RUNTIME_CLASS Macro 


RUNTIME_CLASS( class_name ) 


class_name 
The actual name of the class (without quotes). 


RUNTIME_ CLASS returns a pointer to a CRuntimeClass structure for the class 
specified by class_name. 


CRuntimeClass* prt = RUNTIME_CLASS( CAge ); 
ASSERT( strcemp( prt->m_pszClassName, "CAge" ) == @ ); 


DECLARE_DYNAMIC, CObject::GetRuntimeClass, 
IMPLEMENT_DYNAMIC 


Operators 


Syntax 


Remarks 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 
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CObject::operator = 


void operator =( const CObject& svc ); 


The standard C++ default class assignment behavior is a member-by-member 
copy. The presence of this private assignment operator guarantees a compiler error 
message if you assign without the overridden operator. You must, therefore, pro- 
vide an assignment operator in your derived class if you intend to assign objects of 
your derived class. 


CObject::operator delete 


void operator delete( void* p ); 


For the Release version of the library, delete simply frees the memory allocated 
by new. In the Debug version, delete participates in an allocation-monitoring 
scheme designed to detect memory leaks. 


Note If you override new and delete, you forfeit the diagnostic capability. 


CObject::operator new 


CObject::operator new 


void* operator new( size_t nSize ) 
throw( CMemoryException ); 


void* operator new( size_t nSize, const char FAR* lpszFileName, int nLine ) 
throw( CMemoryException ); 


For the Release version of the library, new performs an optimal memory alloca- 
tion in a manner similar to malloc. In the Debug version, new participates in an 
allocation-monitoring scheme designed to detect memory leaks. 


476 #CObject::operator new 


If you use the code line: 


4edefine new DEBUG NEW 


before any of your implementations in a .CPP file, then the second version of new 
will be used, storing the filename and line number in the allocated block for later 
reporting. You do not have to worry about supplying the extra parameters; a 
macro takes care of that for you. 


Even if you don’t use DEBUG_ NEW in Debug mode, you still get leak detection, 
but without the source file line number reporting described above. 


Note If you override this operator, you must also override delete. Do not use the 
standard library _new_ handler function. 


See Also CObject::operator delete 
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class CObList : public CObject 


See Also 


Derivation 


The CObList class supports ordered lists of non- 
unique CObject pointers accessible sequentially or 
by pointer value. CObList lists behave like doubly 
linked lists. 


A variable of type POSITION is a kind of key for the list. You can use a 
POSITION variable as an iterator to sequentially traverse a list and as a book- 
mark to hold a place. A position is not the same as an index, however. 


Element insertion is very fast at the list head, at the tail, and at a known 
POSITION. A sequential search is necessary in order to look up an element by 
value or index. This search can be slow if the list is long. 


CObList incorporates the IMPLEMENT_SERIAL macro to support serializa- 
tion and dumping of its elements. If a list of CObject pointers is stored to an ar- 
chive, either with the overloaded insertion operator or with the Serialize member 
function, each CObject element is, in turn, serialized. 


If you need a dump of individual CObject elements in the list, you must set the 
depth of the dump context to 1 or greater. 


When a CObList object is deleted, or when its elements are removed, only the 
CObject pointers are removed, not the objects they reference. 


#include <afxcoll.h> 
CStringList, CPtrList 


The tutorial in the Class Library User’s Guide illustrates the derivation of a 
CPersonList class from CObList. This new list class, designed to hold pointers 
to CPerson objects, adds a new data member and new member functions. Note 
that the resulting list is not strictly “type safe” because it allows insertion of any 
CObject pointer. 


Note You must use the IMPLEMENT_SERIAL macro in the implementation of 
your derived class if you intend to serialize the list. 
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Public Members 


Construction/Destruction 


CObList Constructs an empty list for CObject pointers. 

~CObList Destroys a CObList object. 

Head/Tail Access 

GetHead Returns the head element of the list (cannot be 
empty). 

GetTail Returns the tail element of the list (cannot be 
empty). 

Operations 

RemoveHead Removes the element from the head of the list. 

RemoveTail Removes the element from the tail of the list. 

AddHead Adds an element (or all the elements in another 
list) to the head of the list (makes a new head). 

AddTail Adds an element (or all the elements in another 
list) to the tail of the list (makes a new tail). 

RemoveAll Removes all the elements from this list. 

lteration 

GetHeadPosition Returns the position of the head element of the list. 

GetTailPosition Returns the position of the tail element of the list. 

GetNext Gets the next element for iterating. 

GetPrev Gets the previous element for iterating. 


Retrieval/Modification 


GetAt Gets the element at a given position. 
SetAt Sets the element at a given position. 
RemoveAt Removes an element from this list, specified by 


position. 


Insertion 
InsertBefore 
InsertAfter 


Searching 
Find 


FindIndex 
Status 


GetCount 
IsEmpty 
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Inserts a new element before a given position. 


Inserts a new element after a given position. 


Gets the position of an element specified by 
pointer value. 


Gets the position of an element specified by a zero- 
based index. 


Returns the number of elements in this list. 


Tests for the empty list condition (no elements). 
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Member Functions 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


CObList::AddHead 


POSITION AddHead( CObject* newElement ) 
throw( CMemoryException ); 


void AddHead( CObList* pNewList ) 
throw( CMemoryException ); 


newElement | 
The CObject pointer to be added to this list. 


pNewList 
A pointer to another CObList list. The elements in pNewList will be added to 
this list. 


Adds a new element or list of elements to the head of this list. The list may be 
empty before the operation. 


The first version returns the POSITION value of the newly inserted element. 


CObList list; 


list.AddHead( new CAge( 21 ) ); // 21 is now at head 
list.AddHead( new CAge( 4@ ) ); // 4@ replaces 21 at head 
d:ifdef _DEBUG 
afxDump.SetDepth( 1 ); 
afxDump << "AddHead example: " << &list << "\\n"; 
dtendi f 3 


The results from this program are as follows: 


AddHead example: A CObList with 2 elements 
a CAge at $44A8 4@ 
a CAge at $442A 21 


CObList::GetHead, CObList:: RemoveHead 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


CObList::AddTail 481 


CObList::AddTail 


POSITION AddTail( CObject* newElement ) 
throw( CMemoryException ); 


void AddTail( CObList* pNewList ) 
throw( CMemoryException ); 


newElement 
The CObject pointer to be added to this list. 


pNewList 
A pointer to another CObList list. The elements in pNewList will be added to 
this list. 


Adds a new element or list of elements to the tail of this list. The list may be 
empty before the operation. 


The first version returns the POSITION value of the newly inserted element. 


CObList list; 

list.AddTail( new CAge( 21 ) ); 

list.AddTail( new CAge( 4@ ) ); // List now contains (21, 40) 
dFifdef _ DEBUG 

afxDump.SetDepth( 1 ); 

afxDump << "AddTail example: " << &list << "\\n"; 
ftendif 


The results from this program are as follows: 


AddTail example: A CObList with 2 elements 
a CAge at $444A 21 
a CAge at $4526 40 


CObList::GetTail, CObList::RemoveTail 


482 CObList::CObList 


Syntax 


Parameters 


Remarks 


Example 


CObList::CObList 


CObList( int nBlockSize = 10 ); 


nBlockSize 
The memory-allocation granularity for extending the list. 


Constructs an empty CObject pointer list. As the list grows, memory is allocated 
in units of nBlockSize entries. If a memory allocation fails, a CMemoryException 
is thrown. 


Below is a listing of the CObject-derived class CAge used in all the collection ex- 
amples: 


// Simple CObject-derived class for CObList examples 
class CAge : public CObject 


DECLARE_SERIAL( CAge ) 
private: 
int m_years; 
public: 
CAge() { m_years = Q@; } 
CAge( int age ) { m_years = age; } 
CAge( const CAge& a ) { m_years = a.m_years; } // Copy constructor 
void Serialize( CArchivea& ar); 
void AssertValid() const; 
const CAge& operator=( const CAge& a ) 


{ 
m_years = a.m_years; return *this; 
} 
BOOL operator==(CAge a) 
{ 
return m_years == a.m_years; 
i 


#Fifdef _DEBUG. 
void Dump( CDumpContext& dc ) const 


{ 
CObject::Dump( dc ); 
dc << m_years; 

} 


fHendif 
ae 


syntax 


Remarks 


Syntax 


Parameters 


Remarks 


Return Value 
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Below is an example of CObList constructor usage: 


CObList list( 2@ ); // List on the stack with blocksize = 20 


CObList* plist = new CObList; // List on the heap with default blocksize 


CObList::~CObList 


~CObListQ; 


Destroys a CObList object but does not destroy the CObject objects that are refer- 
enced in the list. 


CObList::Find 


POSITION Find( CObject* searchValue, 
POSITION startAfter = NULL ) const; 


searchValue 
The object pointer to be found in this list. 


startAfter 
The start position for the search. 


Searches the list sequentially to find the first CObject pointer matching the 
specified CObject pointer. Note that the pointer values are compared, not the con- 
tents of the objects. 


A POSITION value that can be used for iteration or object pointer retrieval; 
NULL if the object is not found. 
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Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


CObList list; 
CAge* pal; 
CAge* pa2; 
POSITION pos; 


list.AddHead( pal = new CAge( 21 ) ); 

list.AddHead( pa2 = new CAge( 40 ) ); // List now contains (40, 21) 

if( ( pos = list.Find( pal ) ) != NULL ) // Hunt for pal, 

{ // starting at head by default 
ASSERT( *(CAge*) list.GetAt( pos ) == CAge( 21 ) ); 

} 


CObList::GetNext, CObList::GetPrev 


CObList::Findindex 


POSITION FindIndex( int n/ndex ) const; 


nIndex 
The zero-based index of the list element to be found. 


Uses the value of nJndex as an index into the list. It starts a sequential scan from 
the head of the list, stopping on the nth element. 


A POSITION value that can be used for iteration or object pointer retrieval; 
NULL if nIndex is negative or too large. 


CObList list; 
POSITION pos; 


list.AddHead( new CAge( 21 ) ); 
list.AddHead( new CAge( 4@ ) ); // List now contains (4@, 21) 
if( ( pos = list.FindIndex( @ )) != NULL ) 
{ 
ASSERT( *(CAge*) list.GetAt( pos ) == CAge( 4@ ) ); 
} 


CObList::Find, CObList::GetNext, CObList::GetPrev 
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CObList::GetAt 


Syntax CObject* & GetAt( POSITION position ); 
CObject* GetAt( POSITION position ) const; 


Parameters position 
A POSITION value returned by a previous BeginIterate or Find member 
function call. 


Remarks A variable of type POSITION is a kind of “key” for the list. It is not the same as 
an index, and you cannot operate on a POSITION value yourself. GetAt retrieves 
the CObject pointer associated with a given position. 


You must ensure that your POSITION value represents a valid position in the list. 
If it is invalid, then the Debug version of the library asserts. 


Return Value See the return value description for GetHead. 

Example See the example for FindIndex 

See Also CObList::Find, CObList::SetAt, CObList::GetNext, CObList::GetPrev, 
CObList::GetHead 


CObList::GetCount 


Syntax int GetCount() const; 
Remarks Gets the number of elements in this list. 


Return Value An integer value containing the element count. 
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Example 


See Also 


syntax 


Remarks 


Return Value 


Example 


CObList list; 


list.AddHead( new CAge( 21 
list.AddHead( new CAge( 40 
ASSERT( 1list.GetCount() 


PO we we 


; // List now contains (4@, 21) 


CObList:: IsEmpty 


CObList::GetHead 


CObject*& GetHeadQ); 
CObject* GetHead() const; 


Gets the CObject pointer that represents the head element of this list. 


You must ensure that the list is not empty before calling GetHead. If the list is 
empty, then the Debug version of the library asserts. Use IsEmpty to verify that 
the list contains elements. 


If the list is accessed through a pointer to a const CObList, then GetHead returns 
a CObject pointer. This allows the function to be used only on the right side of an 
assignment statement and thus protects the list from modification. 


If the list is accessed directly or through a pointer to a CObList, then GetHead re- 
turns a reference to a CObject pointer. This allows the function to be used on 
either side of an assignment statement and thus allows the list entries to be 
modified. 


The following example illustrates the use of GetHead on the left side of an assign- 
ment statement. 


const CObList* cplist; 


CObList* plist = new CObList; 
CAge* pagel new CAge( 21 ); 
CAge* page2 = new CAge( 30 ); 
CAge* page3 = new CAge( 40 ); 


See Also 


Syntax 
Remarks 


Return Value 


Example 


See Also 
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plist->AddHead( pagel ); 

plist->AddHead( page2 ); // List now contains (30, 21) 
// The following statement REPLACES the head element 
plist->GetHead() = page3; // List now contains (4@, 21) 
ASSERT( *(CAge*) plist->GetHead() == CAge( 4@ ) ); 


cplist = plist; // cplist is a pointer to a const list 
// cplist->GetHead() = page3; // Does not compile! 
ASSERT( *(CAge*) plist->GetHead() == CAge( 4@ ) ); // OK 


delete pagel; 
delete page2; 
delete page3; 
delete plist; // Cleans up memory 


CObList::GetTail, CObList::GetTailPosition, CObList:: AddHead, 
CObList:: RemoveHead 


CObList::GetHeadPosition 


POSITION GetHeadPosition() const; 
Gets the position of the head element of this list. 


A POSITION value that can be used for iteration or object pointer retrieval; 
NULL if the list is empty. 


CObList list; 
POSITION pos; 


list.AddHead( new CAge( 21 ) ); 
list.AddHead( new CAge( 40 ) ); // List now contains (4@, 21) 
if( ( pos = list.GetHeadPosition()) != NULL ) 
{ 
ASSERT( *(CAge*) list.GetAt( pos ) == CAge( 4@ ) ); 
} 


CObList::GetTailPosition 
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Syntax 


Parameters 


Remarks 


Return Value 


Example 


CObList::GetNext 


CObject* & GetNext( POSITION& rPosition ); 
CObject* GetNext( POSITION& rPosition ) const; 


rPosition 
A reference to a POSITION value returned by a previous GetNext, 
GetHeadPosition, or other member function call. 


GetNext gets the list element identified by rPosition, then sets rPosition to the 
POSITION value of the next entry in the list. You can use GetNext in a forward 
iteration loop if you establish the initial position with a call to GetHeadPosition 
or Find. 


You must ensure that your POSITION value represents a valid position in the list. 
If it is invalid, then the Debug version of the library asserts. 


If the retrieved element is the last in the list, then the new value of rPosition is set 
to NULL. 


It is possible to remove an element during an iteration. See the example for 
RemoveAt. 


See the return value description for GetHead. 


CObList list; 
POSITION pos; 


list.AddHead( new CAge( 21 ) ); 
list.AddHead( new CAge( 4@ ) ); // List now contains (4@, 21) 
// Iterate through the list in head-to-tail order 
for( pos = list.GetHeadPosition(); pos != NULL; ) 
{ 
#Fifdef _ DEBUG 
afxDump << list.GetNext( pos ) << "\\n"; 
dFendif 
} 
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The results from this program are as follows: 


a CAge at $479C 40 
a CAge at $46C@ 21 


See Also CObList::Find, CObList::GetHeadPosition, CObList::GetTailPosition, 
CObList::GetPrev, CObList::GetHead 


CObList::GetPrev 


Syntax CObject* & GetPrev( POSITION& rPosition ); 
CObject* GetPrev( POSITION& rPosition ) const; 


Parameters rPosition 
A reference to a POSITION value returned by a previous GetPrev or other 
member function call. 


Remarks GetPrev gets the list element identified by rPosition, then sets rPosition to the 
POSITION value of the previous entry in the list. You can use GetPrev in a 
reverse iteration loop if you establish the initial position with a call to 
GetTailPosition or Find. 


You must ensure that your POSITION value represents a valid position in the list. 
If it is invalid, then the Debug version of the library asserts. 


If the retrieved element ts the first in the list, then the new value of rPosition 1s set 


to NULL. 
Return Value See the return value description for GetHead. 
Example CObList list; 


POSITION pos; 


list.AddHead( new CAge(21) ); 
list.AddHead( new CAge(4@) ); // List now contains (4@, 21) 
// Iterate through the list in tail-to-head order 
for( pos = list.GetTailPosition(); pos != NULL; ) 
{ 
d:ifdef _DEBUG 
afxDump << list.GetPrev( pos ) << "\n"; 
dtendif 
} 
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See Also 


Syntax 


Remarks 


Return Value 


Example 


See Also 


The results from this program are as follows: 


a CAge at $421C 21 
a CAge at $421C 40 


CObList::Find, CObList::GetTailPosition, CObList::GetHeadPosition, 
CObList::GetNext, CObList::GetHead 


CObList::GetTail 


CObject* & GetTailQ; 
CObject* GetTail() const; 


Gets the CObject pointer that represents the tail element of this list. 


You must ensure that the list is not empty before calling GetTail. If the list is 
empty, then the Debug version of the library asserts. Use IsEmpty to verify that 
the list contains elements. 


See the return value description for GetHead. 


CObList list; 


list.AddHead( new CAge( 21 ) ); 
list.AddHead( new CAge( 4@ ) ); // List now contains (40, 21) 
ASSERT( *(CAge*) list.GetTail() == CAge( 21 ) ); 


CObList::GetTail, CObList:: AddHead, CObList:: RemoveHead, 
CObList::GetHead 


Syntax 
Remarks 


Return Value 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Example 
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CObList::GetTailPosition 


POSITION GetTailPosition( const; 
Gets the position of the tail element of this list; NULL if the list is empty. 


A POSITION value that can be used for iteration or object pointer retrieval; 
NULL if the list is empty. 


CObList list; 
POSITION pos; 


list.AddHead( new CAge( 21 ) ); 
list.AddHead( new CAge( 4@ ) ); // List now contains (4@, 21) 
if( ( pos = list.GetTailPosition() ) != NULL ) 
{ 
ASSERT( *(CAge*) list.GetAt( pos ) == CAge( 21 ) ); 
} 


CObList::GetHeadPosition, CObList::GetTail 


CObList::InsertAfter 


POSITION InsertAfter( POSITION position, CObject* newElement ); 
throw ( CMemoryException ); 


position 
A POSITION value returned by a previous GetNext, GetPrev, or Find mem- 
ber function call. 


newElement 
The object pointer to be added to this list. 


Adds an element to this list ’after’ the element at the specified position. 


CObList list; 
POSITION posl, pos2; 


list.AddHead( new CAge( 21 ) ); 

list.AddHead( new CAge( 4@ ) ); // List now contains (4@, 21) 
if( ( posl = list.GetHeadPosition() ) != NULL ) 

{ 
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See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


pos2 = list.InsertAfter( posl, new CAge( 65 ) ); 
} 
#Fifdef _ DEBUG 
afxDump.SetDepth( 1 ); 
afxDump << “InsertAfter example: " << &list << "\\n"; 
HFendif 


The results from this program are as follows: 


InsertAfter example: A CObList with 3 elements 
a CAge at $4A44 40 
a CAge at $4A64 65 
a CAge at $4968 21 


CObList::Find, CObList::InsertBefore 


CObList::InsertBefore 


POSITION InsertBefore( POSITION position, CObject* newElement ) 
throw ( CMemoryException ); 


position 
A POSITION value returned by a previous GetNext, GetPrev, or Find mem- 
ber function call. 


newElement 
The object pointer to be added to this list. 


Adds an element to this list before’ the element at the specified position. 


A POSITION value that can be used for iteration or object pointer retrieval; 
NULL if the list is empty. 


CObList list; 
POSITION posl, pos2; 


list.AddHead( new CAge( 21 ) ); 
list.AddHead( new CAge( 4@ ) ); // List now contains (40, 21) 
if( ( posl = list.GetTailPosition() ) != NULL ) 
{ 
pos2 = list.InsertBefore( posl, new CAge( 65 ) ); 
} 


See Also 


Syntax 
Remarks 
Return Value 
Example 


See Also 


Syntax 


Remarks 


CObList::RemoveAll 


#Hifdef _ DEBUG 

afxDump.SetDepth( 1 ); 

afxDump << "“InsertBefore example: " << &list << "\\n"; 
dFrendif 


The results from this program are as follows: 


InsertBefore example: A CObList with 3 elements 
a CAge at $4AE2 40 
a CAge at $4B@2 65 
a CAge at $4956 21 


CObList::Find, CObList::InsertAfter 


CObList::lsEmpty 

BOOL IsEmpty() const; 

Indicates if this list contains no elements. 
TRUE if this list is empty; FALSE otherwise. 
See the example for RemoveAll. 


CObList::GetCount 


CObList::RemoveaAll 


void RemoveAllQ); 


493 


Removes all the elements from this list and frees the associated CObList memory. 


No error is generated if the list is already empty. 


When you remove elements from a CObList, you remove the object pointers from 


the list. It is your responsibility to delete the objects themselves. 
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Example 


Syntax 


Parameters 


Remarks 


Example 


CObList list; 
CAge* pal; 
CAge* pa2; 


ASSERT( list.IsEmpty()); // Yes it is 

list.AddHead( pal = new CAge( 21 ) ); 

list.AddHead( pa2 = new CAge( 40 ) ); // List now contains (40, 21) 
ASSERT( !list.IsEmpty()); // No it isn't 

list.RemoveAl1l(); // CAge's aren't destroyed 

ASSERT( list.IsEmpty()); // Yes it is 

delete pal; // Now delete the CAge objects 

delete pa2; 


CObList::RemoveAt 


void RemoveAt( POSITION position ); 


position 
The position of the element to be removed from the list. 


Removes the specified element from this list. 


When you remove an element from a CObList, you remove the object pointer 
from the list. It is your responsibility to delete the objects themselves. 


You must ensure that your POSITION value represents a valid position in the list. 
If it is invalid, then the Debug version of the library asserts. 


Be careful when removing an element during a list iteration. The following ex- 
ample shows a removal technique that guarantees a good POSITION value for 
GetNext: 


CObList list; 
POSITION posl, pos2; 
CObject* pa; 


list.AddHead( new CAge( 21 ) ); 

list.AddHead( new CAge( 4@ ) ); 

list.AddHead( new CAge( 65 ) ); // List now contains (65 40, 21) 
for( posl = list.GetHeadPosition(); ( pos2 = posl ) != NULL; ) 

{ 


Syntax 


Remarks 


Return Value 


Example 


See Also 
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if( *(CAge*) list.GetNext( posl ) == CAge( 4@ ) ) 


{ 
pa = list.GetAt( pos2 ); // Save the old pointer for deletion 
list.RemoveAt( pos2 ); 
delete pa; // Deletion avoids memory leak 

} 


i 
#Hifdef _DEBUG 

afxDump.SetDepth( 1 ); 

afxDump << “RemoveAt example: " << &list << "\\n"; 
fendi f 


The results from this program are as follows: 


RemoveAt example: A CObList with 2 elements 
a CAge at $4C1E 65 
a CAge at $4B22 21 


CObList::RemoveHead 


CObject* RemoveHeadQ); 


Removes the element from the head of the list and returns a pointer to it. 


You must ensure that the list is not empty before calling RemoveHead. If the list 
is empty, then the Debug version of the library asserts. Use IsEmpty to verify that 
the list contains elements. 


The CObject pointer previously at the head of the list. 


CObList list; 
CAge* pal; 
CAge* pa2; 


list.AddHead( pal = new CAge( 21 ) ) 
list.AddHead( pa2 = new CAge( 4@ ) ); // List now contains (4@, 21) 
ASSERT( *(CAge*) list.RemoveHead() == CAge( 40 ) ); // Old head 
ASSERT( *(CAge*) list.GetHead() == CAge( 21 ) ); // New head 
delete pal; 

delete pa2; 


CObList::GetHead, CObList::AddHead 
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Syntax 


Remarks 


Return Value 


Example 


See Also 


syntax 


Parameters 


Remarks 


CObList::RemovetTail 


CObject* RemoveTailQ); 


Removes the element from the tail of the list and returns a pointer to it. 


You must ensure that the list is not empty before calling RemoveTail. If the list is 
empty, then the Debug version of the library asserts. Use IsEmpty to verify that 
the list contains elements. 


A pointer to the object that was at the tail of the list. 


CObLISt: list: 
CAge* pal; 
CAge* paz; 


list.AddHead( pal new CAge( 21 ) ); 
list.AddHead( pa2 = new CAge( 4@ ) ); // List now contains (40, 21) 
ASSERT( *(CAge*) list.RemoveTail() == CAge( 21 ) ); // Old tail 
ASSERT( *(CAge*) list.GetTail() == CAge( 4@ ) ); // New tail 
delete pal; 

delete pa2; // Clean up memory 


CObList::GetTail, CObList::AddTail 


CObList::SetAt 


void SetAt( POSITION pos, CObject* newElement ); 


pos 
The POSITION of the element to be set. 


newElement 
The CObject pointer to be written to the list. 


A variable of type POSITION is a kind of “key” for the list. It is not the same as 
an index, and you cannot operate on a POSITION value yourself. SetAt writes 
the CObject pointer to the specified position in the list. 


You must ensure that your POSITION value represents a valid position in the list. 
If it is invalid, then the Debug version of the library asserts. 


Example 


See Also 
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CObList list; 
CObject* pa; 
POSITION pos; 


list.AddHead( new CAge( 21 ) ); 
list.AddHead( new CAge( 4@ ) ); // List now contains (40, 21) 
if( ( pos = list.GetTailPosition()) != NULL ) 


{ 
pa = list.GetAt( pos ); // Save the old pointer for deletion 
list.SetAt( pos, new CAge( 65 ) ); // Replace the tail element 
delete pa; // Deletion avoids memory leak 

} 


ifdef _DEBUG 

afxDump.SetDepth( 1 ); 

afxDump << "SetAt example: " << &list << "\\n"; 
#Fendi f 


The results from this program are as follows: 


SetAt example: A CObList with 2 elements 
a CAge at $4D98 40 
a CAge at $4DB8 65 


CObList::Find, CObList::GetAt, CObList::GetNext, CObList::GetPrev 
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class CPaintDC : public CDC 


The CPaintDC class is a device-context class derived 
from CDC. It performs a BeginPaint at construction 
time and EndPaint at destruction time. 


A CPaintDC object can only be used when respond- 
ing to a WM_ PAINT message, usually in your 
OnPaint message-handler member function. 


See Also CDC 


Public Members 


Data Members 


m_ps Contains the PAINTSTRUCT used to paint the 
client area. 


Construction/Destruction 


CPaintDC Constructs a CPaintDC connected to the specified 
CWhnd. 
~CPaintDC Destroys a CPaintDC. 


Protected Members 


m_hWnd The HWND to which this CPaintDC object is 
attached. 
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Member Functions 


Syntax 


Parameters 


Remarks 


Syntax 


Remarks 


CPaintDC::CPaintDC 


CPaintDC( CWnd* pWid ) 
throw( CResourceException ); 


pWnd 
Points to the CWnd object to which the CPaintDC object belongs. 


Constructs a CPaintDC object, prepares the application window for painting, and 
stores the PAINTSTRUCT structure in the m_ ps member variable. 


An exception (of type CResourceException) is thrown if the Windows GetDC 
call fails. A device context may not be available if Windows has already allocated 


all of its available device contexts. Your application competes for the five com- 
mon display contexts available at any given time under Windows. 


CPaintDC::~CPaintDC 


virtual ~CPaintDC() 


Destroys a CPaintDC object and marks the end of painting the application win- 
dow. In the process, the destructor destroys the paint structure. 
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Data Members 


CPaintDC::m_hWhd 


Remarks The HWND to which this CPaintDC object is attached. m_ hWnd is a protected 
variable of type HWND. 


CPaintDC::m_ps 


Remarks m_ps is a public member variable of type PAINTSTRUCT. It is the 
PAINTSTRUCT that is passed to and filled out by CWnd::BeginPaint. 


The PAINTSTRUCT contains information that the application uses to paint the 
client area of the window associated with a CPaintDC object. 


The PAINTSTRUCT structure looks like this: 


typedef struct tagPAINTSTRUCT { 
HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[16]; 
} PAINTSTRUCT; 


Note You can access the device-context handle through the PAINTSTRUCT. 


However, you can access the handle more directly through the m_hDC member 
variable, which CPaintDC inherits from CDC. 
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class CPalette : public CGdiObject 


The CPalette class encapsulates a Windows color 
palette. A palette provides an interface between an 
application and a color output device (such as a dis- 
play device). The interface allows the application to 
take full advantage of the color capabilities of the out- 
put device without severely interfering with the colors 
displayed by other applications. Windows uses the application’s logical palette (a 
list of needed colors) in conjunction with the system palette (which defines availa- 
ble colors) to determine the colors used. 


A CPalette object provides member functions for manipulating the palette re- 
ferred to by the object. Construct a CPalette object and use its member functions 
to create the actual palette (a GDI object) and to manipulate its entries and other 
properties. 


Public Members 


Construction/Destruction 


CPalette Constructs a CPalette object with no attached 
Windows palette. You must initialize the CPalette 
object with one of the other member functions 
before it can be used. 


Initialization 


CreatePalette Initializes a CPalette object by creating a 
Windows color palette and attaching the palette to 
the CPalette object. 

Operations 

FromHandle Returns a pointer to a CPalette object when given 


a handle to a Windows palette object. If a 
CPalette object is not already attached to the 
Windows palette, a temporary CPalette object is 
created and attached. 


GetPaletteEntries Retrieves a range of palette entries in a logical 
palette. 


902 


CPalette 


SetPaletteEntries 


AnimatePalette 


GetNearestPaletteIndex 


ResizePalette 


Sets RGB color values and flags in a range of en- 
tries in a logical palette. 


Replaces entries in the logical palette identified by 
the CPalette object. The application does not have 
to update its client area because Windows maps 

the new entries into the system palette immediately. 


Returns the index of the entry 1n the logical palette 
that most closely matches a color value. 


Changes the size of the logical palette specified by 
the CPalette object to the specified number of 
entries. 
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Member Functions 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


CPalette::AnimatePalette 


void AnimatePalette( UINT nStartIndex, UINT nNumEntries, 
LPPALETTEENTRY /pPaletteColors ); 


nStartIndex 
Specifies the first entry in the palette to be animated. 


nNumEntries 
Specifies the number of entries in the palette to be animated. 


lpPaletteColors 
Points to the first member of an array of PALETTEENTRY structures to 
replace the palette entries identified by nStartIndex and nNumEntries. 


Replaces entries in the logical palette attached to the CPalette object. When an 


application calls AnimatePalette, it does not have to update its client area because 
Windows maps the new entries into the system palette immediately. 


The AnimatePalette function will only change entries with the PC_RESERVED 
flag set in the corresponding palPaletteEntry member of the LOGPALETTE 
structure that is attached to the CPalette object. 


CPalette::CreatePalette, :: AnimatePalette 


CPalette::CPalette 


CPaletteQ( ; 


Constructs a CPalette object. The object has no attached palette until you call 
CreatePalette to attach one. 


CPalette::CreatePalette 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


‘:CreatePalette 


CPalette::CreatePalette 


BOOL CreatePalette( LPLOGPALETTE /[pLogPalette ); 


lpLogPalette 
Points to a LOGPALETTE structure that contains information about the 
colors in the logical palette. 


The LOGPALETTE structure has the following form: 


typedef struct tagLOGPALETTE { 
WORD palVersion; 
WORD palNumEntries; 
PALETTEENTRY palPalEntryL1]; 
} LOGPALETTE; 


Initializes a CPalette object by creating a Windows logical color palette and 
attaching it to the CPalette object. 


TRUE if successful; otherwise FALSE. 


::CreatePalette 


CPalette::FromHandle 


static CPalette* FromHandle( HPALETTE /hPalette ); 


hPalette 
A handle to a Windows GDI color palette. 


Returns a pointer to a CPalette object when given a handle to a Windows palette 
object. If a CPalette object is not already attached to the Windows palette, a tem- 
porary CPalette object is created and attached. This temporary CPalette object is 
valid only until the next time the application has idle time in its event loop, at 
which time all temporary graphic objects are deleted. In other words, the tem- 
porary object is only valid during the processing of one window message. 


A pointer to a CPalette object if successful; otherwise NULL. 
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CPalette::GetNearestPalettelndex 


Syntax UINT GetNearestPaletteIndex( DWORD crColor ) const; 


Parameters crColor 
Specifies the color to be matched. 


Remarks Returns the index of the entry in the logical palette that most closely matches the 
specified color value. 


Return Value The index of an entry in a logical palette. The entry contains the color that most 
nearly matches the specified color. 


See Also ::GetNearestPaletteIndex 


CPalette::GetPaletteEntries 


Syntax UINT GetPaletteEntries( UINT nStartIndex, UINT nNumEntries, 
LPPALETTEENTRY /pPaletteColors ) const; 


Parameters nStartIndex 
Specifies the first entry in the logical palette to be retrieved. 


nNumEntries 
Specifies the number of entries in the logical palette to be retrieved. 


lpPaletteColors 
Points to an array of PALETTEENTRY data structures to receive the palette 
entries. The array must contain at least as many data structures as specified by 


nNumEntries. 
Remarks Retrieves a range of palette entries in a logical palette. 
Return Value The number of entries retrieved from the logical palette, or 0 if the function failed. 


See Also ::GetPaletteEntries 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


CPalette::ResizePalette 
BOOL ResizePalette( UINT nNumeEntries ); 


nNumEntries 
Specifies the number of entries in the palette after it has been resized. 


Changes the size of the logical palette attached to the CPalette object to the num- 
ber of entries specified by nNumEntries. If an application calls ResizePalette to 
reduce the size of the palette, the entries remaining in the resized palette are un- 
changed. If the application calls ResizePalette to enlarge the palette, the additional 
palette entries are set to black (the red, green, and blue values are all 0) and the 
flags for all additional entries are set to 0. 


TRUE if the palette was successfully resized; otherwise FALSE. 


::ResizePalette 


CPalette::SetPaletteEntries 


UINT SetPaletteEntries( UINT nStartIndex, UINT nNumEntries, 
LPPALETTEENTRY /pPaletteColors ); 


nStartIndex 
Specifies the first entry in the logical palette to be set. 


nNumEntries 
Specifies the number of entries in the logical palette to be set. 


lpPaletteColors 
Points to an array of PALETTEENTRY data structures to receive the palette 
entries. The array must contain at least as many data structures as specified by 
nNumeEntries. 


Remarks 


Return Value 


See Also 
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Sets RGB color values and flags in a range of entries in a logical palette. 
If the logical palette 1s selected into a device context when the application calls 


SetPaletteEntries, the changes will not take effect until the application calls 
CDC::RealizePalette. 


The number of entries set in the logical palette, or 0 if the function failed. 


CDC::RealizePalette, ::SetPaletteEntries 


508 CPen 


class CPen : public CGdiObject 


The CPen class encapsulates a Windows graphical 
design interface (GDI) pen. 


Public Members 


Construction/Destruction 


CPen Constructs a CPen object. 

Initialization 

CreatePen Initializes a pen with the specified style, width, and 
color. 

CreatePenIndirect Initializes a pen with the style, width, and color 


given in a LOGPEN structure. 


Operations 


FromHandle | Returns a pointer to a CPen object when given a 
Windows HPEN. 
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Member Functions 


Syntax 


Parameters 


Remarks 


CPen::CPen 


CPen(); 


CPen( int nPenStyle, int nWidth, DWORD crColor ) 
throw( CResourceException ); 


nPenStyle 

Specifies the pen style. This parameter can be one of the following values: 

Value Meaning 

PS_SOLID Creates a solid pen. 

PS_ DASH Creates a dashed pen. Valid only when the pen 
width is 1. 

PS_ DOT Creates a dotted pen. Valid only when the pen 
width is 1. 

PS_DASHDOT Creates a pen with alternating dashes and dots. 


Valid only when the pen width is 1. 


PS_DASHDOTDOT Creates a pen with alternating dashes and double- 
dots. Valid only when the pen width is 1. 


PS_NULL Creates a null pen. 


PS_INSIDEFRAME Creates a pen in which a line is drawn inside the 
frame of ellipses and rectangles produced by 
using the Ellipse, Rectangle, and RoundRect 
Windows functions. 


nWidth 

Specifies width (in pixels) of the pen. 
crColor 

Contains an RGB color for the pen. 


If you use the constructor with no arguments, you must initialize the resulting 
CPen object with CreatePen, CreatePenIndirect, or CreateStockObject. If you 
use the constructor that takes arguments, then no further initialization is necessary. 


510 CPen::CreatePen 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


syntax 


Parameters 


The constructor with arguments can throw an exception if errors are encountered, 
while the constructor with no arguments will always succeed. 


CPen::CreatePen, CPen::CreatePenIndirect, 
CGdiObject::CreateStockObject 


CPen::CreatePen 


BOOL CreatePen( int nPenStyle, int nWidth, DWORD crColor ); 


nPenStyle 
Specifies the style for the pen. For a list of posse values, see the nPenStyle 
parameter to the CPen constructor. 


nWidth 
Specifies the width of the pen (in logical units). 


crColor 
Contains an RGB color for the pen. 


Initializes a pen with the specified style, width, and color. The pen can be sub- 
sequently selected as the current pen for any device context. 


Pens that have a width greater than 1 pixel should always have either the 
PS_NULL, PS_SOLID, or PS_INSIDEFRAME style. 


TRUE if the function is successful; otherwise FALSE. 


CPen::CreatePenIndirect, CPen::CPen 


CPen::CreatePenindirect 
BOOL CreatePenIndirect( LPLOGPEN I[pLogPen ); 


lpLogPen 


Points to the Windows LOGPEN structure that contains information about the 


pen. 
The LOGPEN structure has the following form: 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 
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typedef struct tagLOGPEN { 


WORD lopnStyle; 

POINT lopnwWidth; 

COLORREF lopnColor; 
} LOGPEN; 


Initializes a pen that has the style, width, and color given in the structure pointed 
to by /pLogPen. 


Pens that have a width greater than | pixel should always have either the 
PS_NULL, PS_SOLID, or PS_INSIDEFRAME style. 


If a pen has the PS_INSIDEFRAME style and a color that does not match a color 
in the logical color table, the pen is drawn with a dithered color. The 
PS_INSIDEFRAME style is identical to PS_SOLID if the pen width is less than 
or equal to 1. 


TRUE if the function is successful; otherwise FALSE. 


CPen::CreatePen, CPen::CPen 


CPen::FromHandle 


static CPen* FromHandle( HPEN /Pen ); 


hPen 
HPEN handle to Windows GDI pen. 


Returns a pointer to a CPen object given a handle to a Windows GDI pen object. 
If a CPen object is not attached to the handle, a temporary CPen object is created 
and attached. This temporary CPen object is valid only until the next time the ap- 
plication has idle time in its event loop, at which time all temporary graphic ob- 
jects are deleted. In other words, the temporary object is only valid during the 
processing of one window message. 


A pointer to a CPen object if successful; otherwise NULL. 
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class CPoint : public tagPOINT 


The CPoint class is similar to a Windows POINT structure and also includes 
member functions to manipulate CPoint and POINT structures. 


A CPoint object can be used wherever a POINT structure 1s used. 


See Also CRect, CSize 


Public Members 


Construction/Destruction 


CPoint Constructs a CPoint. 

Operations 

Offset Adds separate values to the x and y members of 
the CPoint. 

operator == Checks for equality between two points. 

operator != Checks for inequality between two points. 

operator += Offsets a CPoint by a size. 

operator —= Subtracts a size from the CPoint. 


Operators Returning CPoint Values 
operator + Returns a CPoint offset by a size. 


operator — Returns a CPoint offset by a negative size. 


Operators Returning CSize Values 


operator — Returns the size difference between two points. 
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Member Functions 


Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


CPoint::CPoint 


CPoint(); 
CPoint( int initxX, int initY ); 
CPoint( POINT initPt ); 


CPoint( SIZE initSize ); 
initX 
Sets the x member for the CPoint. 
initY 
Sets the y member for the CPoint. 
initPt 
Windows POINT structure used to initialize CPoint. 
initSize 
Sets the x and y member equal to the corresponding values in cx and cy values 
in initSize. 


Constructs a CPoint object. If no arguments are given, x and y members are not 
initialized. 


CPoint::Offset 


void Offset( int xOffset, int yOffset ); 
void Offset( POINT point ); 
void Offset( SIZE initSize ); 


xOffset 
Specifies the amount to offset the x member of the CPoint. 


yOffset 
Specifies the amount to offset the y member of the CPoint. 
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point 
Specifies the amount to offset the CPoint. 


initSize 
Specifies the amount to offset the CPoint. 


Remarks Adds separate values to the x and y members of the CPoint. 


Return Value A CPoint offset by a POINT, CPoint, or Size. 


Operators 


syntax 


Parameters 


Remarks 


Return Value 


Syntax 


Parameters 


Remarks 


Return Value 


Syntax 


Parameters 


Remarks 


CPoint::operator += 


CPoint::operator == 
BOOL operator ==( POINT point ) const; 


point 
Contains a POINT or CPoint. 


Checks for equality between two points. 


TRUE if the points are equal; otherwise FALSE. 


CPoint::operator != 
BOOL operator !=( POINT point ) const; 


point 
Contains a POINT or CPoint. 


Checks for inequality between two points. 


TRUE if the points are not equal; otherwise FALSE. 


CPoint::operator += 


void operator +=( SIZE size ); 


Size 
Contains a SIZE or a CSize. 


Offsets a CPoint by a size. 
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Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Return Value 


Syntax 


Parameters 


Return Value 


CPoint::operator -—= 
void operator — =( SIZE size ); 


SIZE 
Contains a SIZE or a CSize. 


Subtracts a size from the CPoint. 


CPoint::operator + 


CPoint operator +( SIZE size ) const; 


size 
Contains a SIZE or a CSize. 


A CPoint that is offset by a size. 


CPoint::operator — 


CSize operator — ( POINT point ) const; 
CPoint operator — (SIZE size ) const; 


point 

Contains a POINT or CPoint. 
SIZE 

Contains a SIZE or CSize. 


A CSize that is the difference between two points, or returns a CPoint that is nega- 
tively offset by a size. 
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class CPtrArray : public CObject 


Public Members 


The CPtrArray class supports arrays of void 
pointers. 


| CObject | 
ALLE ULLAL UL ELLER EAL 


SEES 


The member functions of CPtrArray are similar to 
the member functions of class CObArray Because 
of this similarity, you can use the CObArray reference documentation for mem- 
ber function specifics. Wherever you see a CObject pointer as a function parame- 
ter or return value, substitute a pointer to void. 


CObject* CObArray::GetAt( int <nIndex> ) const; 


for example, translates to 


void* CPtrArray::GetAt( int <nIndex> ) const; 


CPtrArray incorporates the IMPLEMENT_ DYNAMIC macro to support run- 
time type access and dumping to a CDumpContext object. If you need a dump of 
individual pointer array elements, you must set the depth of the dump context to 1 
or greater. 


Pointer arrays may not be serialized. 


When a pointer array is deleted, or when its elements are removed, only the point- 
ers are removed, not the entities they reference. 


#include <afxcoll.h> 


Construction/Destruction 


CPtrArray Constructs an empty array for void pointers. 
~CPtrArray Destroys a CPtrArray object. 

Bounds 

GetSize Gets number of elements in this array. 
GetUpperBound Returns the largest valid index. 

SetSize Sets the number of elements to be contained in this 


array. 


018 


CPtrArray 


Operations 
FreeExtra 


RemoveAll 


Element Access 
GetAt 
SetAt 


ElementAt 
Growing the Array 
SetAtGrow 

Add 
Insertion/Removal 
InsertAt 


RemoveAt 


Operators 
operator [ | 


Frees all unused memory above the current upper 
bound. 


Removes all the elements from this array. 


Returns the value at a given index. 


Sets the value for a given index; array not allowed 
to grow. 


Returns a temporary reference to the element 
pointer within the array. 


Sets the value for a given index, growing the array 
if necessary. 


Adds an element to the end of the array; grows the 
array if necessary. 


Inserts an element (or all the elements in another 
array) at a specified index. 


Removes an element at a specific index. 


Sets or gets the element at the specified index. 
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class CPtrList : public CObject 


The CPtrList class supports lists of void pointers. 


“4 
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The member functions of CPtrList are similar to the 
member functions of class CObList Because of this 

similarity, you can use the CObList reference docu- 
mentation for member function specifics. Wherever you see a CObject pointer as 
a function parameter or return value, substitute a pointer to void. 


CObject*& CObList::GetHead() const; 
for example, translates to 


void*& CPtrList::GetHead() const; 


CPtrList incorporates the IMPLEMENT_DYNAMIC macro to support run- 
time type access and dumping to a CDumpContext object. If need a dump of in- 
dividual pointer list elements, you must set the depth of the dump context to 1 or 
greater. 


Pointer lists may not be serialized. 


When a CPtrList object is deleted, or when its elements are removed, only the 
pointers are removed, not the entities they reference. 


#include <afxcoll.h> 


Public Members 


Construction/Destruction 


CPtrList Constructs an empty list for void pointers. 

~CPtrList Destroys a CPtrList object. 

Head/Tail Access 

GetHead Returns the head element of the list (cannot be 
empty). 

GetTail Returns the tail element of the list (cannot be 


empty). 
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CPtrList 


Operations 
RemoveHead 
RemoveTail 
AddHead 


AddTail 


RemoveAll 


lteration 
GetHeadPosition 
GetTailPosition 
GetNext 
GetPrev 


Retrieval/Modification 
GetAt 
SetAt 


RemoveAt 


Insertion 
InsertBefore 
InsertAfter 


Searching 
Find 


FindIndex 
Status 


GetCount 
IsEmpty 


Removes the element from the head of the list. 
Removes the element from the tail of the list. 


Adds an element (or all the elements in another 
list) to the head of the list (makes a new head). 


Adds an element (or all the elements in another 
list) to the tail of the list (makes a new tail). 


Removes all the elements from this list. 


Returns the position of the head element of the list. 
Returns the position of the tail element of the list. 
Gets the next element for iterating. 


Gets the previous element for iterating. 


Gets the element at a given position. 
Sets the element at a given position. 


Removes an element from this list, specified by 
position. 


Inserts a new element before a given position. 


Inserts a new element after a given position. 


Gets the position of an element specified by 
pointer value. 


Gets the position of an element specified by a zero- 
based index. 


Returns the number of elements 1n this list. 


Tests for the empty list condition (no elements). 
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class CRect : public tagRECT 


See Also 


Public Members 


The CRect class is similar to a Windows RECT structure, and also includes mem- 
ber functions to manipulate a CRect and Windows RECT structures. 


A CRect object can be passed as a function parameter wherever a LPRECT or 
RECT structure can be passed. 


A CRect contains member variables that define the top-left and bottom-right 
points of a rectangle. The width or height of the rectangle defined by CRect must 
not exceed 32,767 units. 


When specifying a CRect, you must be careful to construct it so that the top-left 
point is above and to the left of the bottom-right point in the Windows coordinate 
system; otherwise, the CRect will not be recognized by some functions. For ex- 
ample, a top left of (10,10) and bottom right of (20,20) defines a valid rectangle; a 
top left of (20,20) and bottom right of (10,10), an invalid rectangle. 


When using overloaded CRect operators, the first operator must be a CRect; the 
second can be either a RECT or a CRect. 


CPoint, CSize 


Construction/Destruction 


CRect Constructs a CRect object. 

Operations 

Width Calculates the width of CRect. 

Height Calculates the height of CRect. 

Size Calculates the size of CRect. 

TopLeft Returns a reference to the top-left point of CRect. 

BottomRight Returns a reference to the bottom-right point of 
CRect. 

IsRectEmpty Determines whether CRect is empty. CRect is 
empty if the width and/or height are 0. 

IsRectNull Determines if the top, bottom, left, and right 


member variables are all equal to 0. 
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CRect 


PtInRect 


SetRect 
SetRectEmpty 


CopyRect 
EqualRect 
InflateRect 


OffsetRect 


IntersectRect 


UnionRect 


Operators 
operator LPRECT 
operator = 
operator == 


operator != 


operator += 
operator —= 


operator &= 
operator |= 
operator + 
operator — 
operator & 


operator | 


Determines whether the specified point lies within 
CRect. 


Sets the dimensions of CRect. 


Sets CRect to an empty rectangle (all coordinates 
equal to 0). 


Copies the dimensions of a source rectangle to 
CRect. 


Determines whether CRect is equal to the given 
rectangle. 


Increases or decreases the width and height of 
CRect. 


Moves CRect by the specified offsets. 


Sets CRect equal to the intersection of two rectan- 
gles. | 


Sets CRect equal to the union of two rectangles. 


Converts a CRect to a LPRECT. 
Copies the dimensions of a rectangle to CRect. 
Determines whether CRect is equal to a rectangle. 


Determines whether CRect is not equal to a rec- 
tangle. 


Adds the specified offsets to CRect. 
Subtracts the specified offsets from CRect. 


Sets CRect equal to the intersection of CRect and 
a rectangle. 


Sets CRect equal to the union of CRect and a rec- 
tangle. 


Adds the given offsets to CRect and returns the re- 
sulting CRect. 


Subtracts the given offsets from CRect and returns 
the resulting CRect. 


Creates the intersection of CRect and a rectangle, 
and returns the resulting CRect. 


Creates the union of CRect and a rectangle, and re- 
turns the resulting CRect. 


CRect::CopyRect 


Member Functions 


syntax 
Remarks 


Return Value 


Syntax 


Parameters 


Remarks 


See Also 


CRect::BottomRight 


CPoint& BottomRightQ); 
Returns a reference to the bottom-right point of CRect. 


POINT, a reference to a POINT. 


CRect::CopyRect 


void CopyRect( LPRECT [pSrcRect ); 


lpSrcRect 
Points to the RECT or CRect whose dimensions are to be copied. 


Copies the [pSrcRect rectangle to the CRect. 


::CopyRect, CRect::operator = 
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524 CRect::CRect 


Syntax 


Parameters 


Remarks 


See Also 


CRect::CRect 


CRectQ); 

CRect( int /, int t, int r, int b); 
CRect( const RECT ®& srcRect ); 
CRect( LPRECT IpSrcRect ); 
CRect( POINT point, SIZE size ); 


l 
Specifies the left position of the CRect. 


t 
Specifies the top of the CRect. 


r 
Specifies the right position of the CRect. 


b 
Specifies the bottom of the CRect. 


srcRect | 
Refers to the RECT structure with the dimensions for the CRect object. 


lpSrcRect 
Points to the RECT structure with the dimensions for the CRect object. 

point 
Specifies the origin point for the rectangle to be constructed. Corresponds to the 
top-left corner. 

size 
Specifies the displacement from the top-left corner to the bottom-right corner of 
the rectangle to be constructed. 


Constructs a CRect object. 


The CRect( const RECT& ) and CRect( LPRECT ) member functions perform 
a CopyRect. The other constructors initialize the member variables of the object 
directly. 


CRect::SetRect, CRect::CopyRect, CRect::operator = 


Syntax 


Parameters 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


Syntax 


Parameters 
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CRect::EqualRect 
BOOL EqualRect( LPRECT /pRect ) const; 
lpRect 
Points to a RECT or CRect that contains the upper-left and lower-right corner 


coordinates of a rectangle. 


TRUE if the two rectangles have the same top, left, bottom, and right values; 
otherwise FALSE. 


::EqualRect 


CRect::Height 


int Height() const; 


Calculates the height of CRect by subtracting the top value from the bottom value. 
The resulting value may be negative. 


The height of CRect. 


CRect::InflateRect 


void InflateRect( int x, int y ); 
void InflateRect( SIZE size ); 


x 
Specifies the amount to increase or decrease CRect’s width. It must be negative 
to decrease the width. 


Specifies the amount to increase or decrease CRect’s height. It must be nega- 
tive to decrease the height. 
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Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


size 
Contains a SIZE or CSize that specifies x and y amounts to add to the CRect’s 
height and width. 


InflateRect’s parameters are signed values; positive values inflate the CRect, and 
negative values deflate it. 


When inflated, CRect’s width is increased by two times x, and its height is in- 
creased by two times y. 


::InflateRect 


CRect::IntersectRect 
int IntersectRect( LPRECT /pRectl, LPRECT [pReci2 ); 


lpRectl 
Points to a RECT or CRect that contains a source rectangle. 


lpRect2 
Points to a RECT or CRect that contains a source rectangle. 


Makes the CRect equal to the intersection of two existing rectangles. The intersec- 
tion is the largest rectangle contained in both existing rectangles. 


TRUE if the intersection of the two rectangles is not empty. It is FALSE if the in- 
tersection is empty. 


::IntersectRect, CRect::operator &=, CRect::operator & 
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CRect::lsRectEmpty 


Syntax BOOL IsRectEmpty() const; 

Remarks Determines if CRect is empty. A rectangle is empty if the width and/or height are 
0 or negative. Differs from IsRectNull, which determines if the rectangle is 
NULL. 

Return Value TRUE if CRect is empty. FALSE if CRect is not empty. 

See Also ::IsRectEmpty, CRect::IsRectNull 


CRect::lsRectNull 


Syntax BOOL IsRectNull() const; 


Remarks Determines if the top, left, bottom, and right values of the CRect are all equal to 0. 
Differs from IsRectEmpty, which determines if the rectangle is empty. 


Return Value TRUE if CRect’s top, left, bottom, and right values are all equal to 0; otherwise 
FALSE. 
See Also CRect::IsRectEmpty 


CRect::0ffsetRect 


Syntax void OffsetRect( int x, int y ); 
void OffsetRect( POINT point ); 
void OffsetRect( SIZE size ); 


Parameters x 
Specifies the amount to move left or right. It must be negative to move left. 


Specifies the amount to move up or down. It must be negative to move up. 
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point 

Contains a POINT or CPoint specifying both dimensions by which to move. 
size 

Contains a SIZE or CSize specifying both dimensions by which to move. 


Remarks Moves CRect by the specified offsets. Moves CRect x units along the x-axis and y 
units along the y-axis. The x and y parameters are signed values, so CRect can be 
moved left or right, and up or down. 


CRect::PtinRect 


Syntax BOOL PtInRect( POINT point ) const; 


Parameters point 
Contains a POINT or CPoint. 


Remarks Determines whether the specified point lies within CRect. A point is within 
CRect if it lies on the left or top side, or is within all four sides. A point on the 
right or bottom side is outside CRect. 


Return Value TRUE if the point lies within CRect; otherwise FALSE. 


See Also ::PtInRect 


CRect::SetRect 


Syntax void SetRect( int x/, int y/, int x2, int y2 ); 
Parameters xl 
Specifies the x-coordinate of the upper-left corner. 
yl 
Specifies the y-coordinate of the upper-left corner. 
x2 
Specifies the x-coordinate of the lower-right corner. 
y2 


Specifies the y-coordinate of the lower-right corner. 
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Remarks Sets the dimensions of CRect to the specified coordinates. 


See Also CRect::CRect, CRect::SetRectEmpty, ::SetRect 


CRect::SetRectEmpty 


Syntax void SetRectEmpty(); 
Remarks Creates a NULL rectangle (all coordinates equal to 0). 
See Also ::SetRectEmpty 


CRect::Size 


Syntax CSize Size() const; 
Return Value The CRect width and height encapsulated as the cx and cy member variables of a 
CSize object. 


CRect::TopLeft 


Syntax CPoint& TopLeft(); 


Return Value A reference to the top-left point of CRect. 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


CRect::UnionRect 


int UnionRect( LPRECT /pRect/, LPRECT /pRec?2 ); 


[pRectl 
Points to a RECT or CRect that contains a source rectangle. 


lpRect2 
Points to a RECT or CRect that contains a source rectangle. 


Makes the dimensions of CRect equal to the union of the two source rectangles. 
The union is the smallest rectangle that contains both source rectangles. 


Windows ignores the dimensions of an empty rectangle; that 1s, a rectangle that 
has no height or has no width. 


TRUE if the union is not empty; FALSE if the union is empty. 


::UnionRect, CRect::operator |=, CRect::operator | 


CRect::Width 


int Width() const; 


Calculates the width of CRect by subtracting the left value from the right value. 
The width may be negative. 


The width of CRect. 


Operators 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 
Remarks 


Return Value 


See Also 
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CRect::operator LPRECT 


operator LPRECT(); 


Converts a CRect to a LPRECT, with no need for the AND (&) operator. 


CRect::operator = 


void operator =( const RECT & srcRect ); 


srcRect 
Refers to a source rectangle. 


Copies the dimensions of srcRect to CRect. 


CRect::SetRect, ::CopyRect 


CRect::operator == 
BOOL operator ==( const RECT & rect ) const; 


rect 
Refers to a source rectangle. 


Determines if rect is equal to CRect by comparing the coordinates of their upper- 
left and lower-right corners. 


If the values of these coordinates are equal, returns TRUE; otherwise FALSE. 


::EqualRect 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


syntax 


Parameters 


Remarks 


See Also 


CRect::operator != 
BOOL operator !=( const RECT & rect ) const; 


rect 
Refers to a source rectangle. 


Determines if rect is not equal to CRect by comparing the coordinates of their 
upper-left and lower-right corners. 


TRUE if not equal; otherwise FALSE. 


CRect::operator == 


CRect::operator += 


void operator +=( POINT point ); 


point 
Contains a POINT or CPoint. 


Moves CRect by the specified offsets. Moves CRect x units along the x-axis and y 
units along the y-axis. The x and y parameters are added to CRect. 


CRect::OffsetRect 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CRect::operator |= 


CRect::operator —= 


void operator — =( POINT point ); 


point 
Contains a POINT or CPoint. 


Moves CRect by the specified offsets. Moves CRect x units along the x-axis and y 


units along the y-axis. The x and y parameters are subtracted from CRect. 


CRect::OffsetRect 


CRect::operator &= 
void operator &=( const RECT & rect ); 


rect 
Contains a RECT or CRect. 


Sets CRect equal to the intersection of CRect and rect. The intersection is the 
largest rectangle contained in both rectangles. 


CRect::IntersectRect 


CRect::operator |= 


void operator |=( const RECT & rect ); 


rect 
Contains a CRect or RECT. 


Sets CRect equal to the union of CRect and rect. The union is the smallest rec- 
tangle that contains both source rectangles. 
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See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Windows ignores the dimensions of an empty rectangle; that is, a rectangle that 
has no height or has no width. 


CRect::UnionRect 


CRect::operator + 


CRect operator +( POINT point ) const; 


point 
Contains a POINT or CPoint. 


Returns a new CRect that is equal to CRect displaced by point. Moves the CRect 
point.x units along the x-axis and point.y units along the y-axis. The x and y para- 
meters are added to CRect’s position. 


The CRect resulting from the offset by point. 


CRect::OffsetRect 


CRect::operator — 
CRect operator — ( POINT point ) const; 


point 
Contains a POINT or CPoint. 


A new CRect that is equal to CRect displaced by —point. Moves the Rect —point.x 
units along the x-axis and —point.y units along the y-axis. The x and y parameters 
are subtracted from CRect’s dimensions. 


The CRect resulting from the offset by point. 


CRect::OffsetRect 


syntax 


Parameters 


Return Value 


See Also 


Syntax 


Parameters 


Return Value 


See Also 
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CRect::operator & 
CRect operator &( const RECT& rect2 ) const; 


rect2 
Contains a RECT or CRect. 


A CRect that is the intersection of CRect and rect2. The intersection is the largest 
rectangle contained in both rectangles. 


CRect::IntersectRect 


CRect::operator | 
CRect operator |( const RECT & rect2 ) const; 


rect2 
Contains a RECT or CRect. 


A CRect that is the union of CRect and rect2. A union is the smallest rectangle 
that contains both source rectangles. 


Windows ignores the dimensions of an empty rectangle, that is, a rectangle that 
has no height or has no width. 


CRect::UnionRect 
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class CResourceException : public CException 


A CResourceException object is generated when 
Windows cannot find or allocate a requested resource. 
No further qualification is necessary or possible. 


#include <afxwin.h> 


Public Members 


CResourceException Constructs a CResourceException object. 


Member Functions 


CResourceException::CResourceException 


Syntax CResourceException(); 


Remarks Constructs a CResourceException object. 


Do not use this constructor directly, but rather call the global function 
AfxThrowResourceException. 


See Also Chapter 5, “Exception Processing,’ AfxThrowResourceException 


Public Members 


class CRgn : public CGdiObject 


The CRgn class encapsulates a Windows graphical 
design interface (GDI) region. A region is an elliptical 
or polygonal area within a window. To use regions, 
you use the member functions of class CRgn in con- 
junction with the clipping functions defined as mem- 


bers of class CDC. 
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The member functions of CRgn create, alter, and retrieve information about the re- 
gion object for which they are called. 


Construction/Destruction 


CRen 


Initialization 
CreateRectRgn 
CreateRectRgnIndirect 


CreateEllipticRgn 
CreateEllipticRgnIndirect 


CreatePolygonRgn 


CreatePolyPolygonRgn 


CreateRoundRectRgn 
CombineRgn 


CopyRgn 


Constructs a CRgn object. 


Initializes a CRgn object with a rectangular region. 


Initializes a CRgn object with a rectangular region 
defined by a RECT structure. 


Initializes a CRgn object with an elliptical region. 


Initializes a CRgn object with an elliptical region 
defined by a RECT structure. 


Initializes a CRgn object with a polygonal region. 
The system closes the polygon automatically, if 
necessary, by drawing a line from the last vertex to 
the first. 


Initializes a CRgn object with a region consisting 
of a series of closed polygons. The polygons may 
be disjoint or they may overlap. 


Initializes a CRgn object with a rectangular region 
with rounded corners. 


Initialize a CRgn object so that it is equivalent to 
the union of two specified CRgn objects. 


Initializes a CRgn object so that it is a copy of a 
specified CRgn object. 


938 


CRgn 


Operations 
EqualRgn 


FromHandle 
GetRenBox 


OffsetRgn 
PtInRegion 


RectInRegion 


SetRectRgn 


Checks two CRgn objects to determine whether 
they are equivalent. 


Returns a pointer to a CRgn object when given a 
handle to a Windows region. 


Retrieves the coordinates of the bounding rec- 
tangle of a CRgn object. 


Moves a CRgn object by the specified offsets. 


Determines whether a specified point is in the 
region. 

Determines whether any part of a specified rec- 
tangle is within the boundaries of the region. 


Sets the CRgn object to the specified rectangular 
region. 
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Member Functions 


Syntax 


Parameters 


Remarks 


CRgn::CombineRgn 
int CombineRgn( CRgn* pRgn/, CRgen* pRen2, int nCombineMode ); 


pRenl 
Identifies an existing region. 


pRen2 
Identifies an existing region. 


nCombineMode 
Specifies the operation to be performed when combining the two source re- 
gions. It can be any one of the following values: 
Value Meaning 
RGN_AND Uses overlapping areas of both regions (intersection). 
RGN_COPY — Creates a copy of region 1 (identified by pRgn/). 


RGN_ DIFF Creates a region consisting of the areas of region 1 
(identified by pRgn/) that are not part of region 2 


(identified by pRgn2). 
RGN_OR Combines both regions in their entirety (union). 
RGN_XOR Combines both regions but removes overlapping areas. 


Creates a new GDI region by combining two existing regions. The regions are 
combined as specified by nCombineMode. 


The two specified regions are combined, and the resulting region handle is stored 
in the CRgn object. Thus, whatever region is stored in the CRgn object is re- 
placed by the combined region. 


Note Use CopyRen to simply copy one region into another region. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Specifies the type of the resulting region. It can be one of the following values: 


Value Meaning 

COMPLEXREGION New region has overlapping borders. 
ERROR No new region created. 
NULLREGION New region is empty. 
SIMPLEREGION New region has no overlapping borders. 


CRegn::CopyR¢gn, ::CombineRgn 


CRgn::CopyRgn 
int CopyRgn( CRgn* pRenSrc ); 


pRensSrc 
Identifies an existing region. 


Copies the region defined by pRgnSrc into the CRgn object. The new region re- 
places the region formerly stored in the CRgn object. This function is a special 
case of CombineRgn. 


Specifies the type of the resulting region. It can be one of the following values: 


Value Meaning 

COMPLEXREGION New region has overlapping borders. 
ERROR No new region created. 
NULLREGION New region is empty. 
SIMPLEREGION New region has no overlapping borders. 


CRgn::CombineRgn, ::CombineRgn 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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CRgn::CreateEllipticRgn 
BOOL CreateEllipticRgn( int x/, int y/, int x2, int y2 ); 


xl 
Specifies the x-coordinate of the upper-left corner of the bounding rectangle of 
the ellipse. 


yl 
Specifies the y-coordinate of the upper-left corner of the bounding rectangle of 
the ellipse. 


ye 
Specifies the x-coordinate of the lower-right corner of the bounding rectangle 
of the ellipse. 


y2 
Specifies the y-coordinate of the lower-right corner of the bounding rectangle 
of the ellipse. 


Creates an elliptical region. The region is defined by the bounding rectangle 
specified by x/, y/, x2, and y2. The region is stored in the CRgn object. 


TRUE if the operation succeeded; otherwise FALSE. 


CRen::CreateEllipticRgnIndirect, ::CreateEllipticRgn 


CRgn::CreateEllipticRgnindirect 
BOOL CreateEllipticRgnIndirect( LPRECT /pRect ); 
lpRect 
Points to a RECT structure or CRect object that contains the coordinates of the 


upper-left and lower-right corners of the bounding rectangle of the ellipse. 


Creates an elliptical region. The region is defined by /pRect and 1s stored in the 
CRen object. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


TRUE if the operation succeeded; otherwise FALSE. 


CRegn::CreateEllipticRgn, ::CreateEllipticRgnIndirect 


CRgn::CreatePolygonRgn 
BOOL CreatePolygonRgn( LPPOINT [pPoints, int nCount, int wMode ); 


lpPoints 
Points to an array of POINT structures or an array of CPoint objects. Each 
structure specifies the x- and y-coordinate of one vertex of the polygon. 


nCount 
Specifies the number of POINT structures or CPoint objects in the array 
pointed to by /pPoints. 


nMode 
Specifies the filling mode for the region. This parameter may be either 
ALTERNATE or WINDING. 


Creates a polygonal region. The system closes the polygon automatically, if neces- 
sary, by drawing a line from the last vertex to the first. The resulting region is 
stored in the CRgn object. 


When the polygon-filling mode is ALTERNATE, the system fills the area be- 
tween odd-numbered and even-numbered polygon sides on each scan line. That is, 
the system fills the area between the first and second side, between the third and 
fourth side, and so on. 


When the polygon-filling mode is WINDING, the system uses the direction in 
which a figure was drawn to determine whether to fill an area. Each line segment 
in a polygon is drawn in either a clockwise or a counterclockwise direction. When- 
ever an imaginary line drawn from an enclosed area to the outside of a figure 
passes through a clockwise line segment, a count is incremented. When the line 
passes through a counterclockwise line segment, the count is decremented. The 
area is filled if the count is nonzero when the line reaches the outside of the figure. 


TRUE if the operation succeeded; otherwise FALSE. 


CRen::CreatePolyPolygonRen, ::CreatePolygonRgn 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CRgn::CreatePolyPolygonRgn 


BOOL CreatePolyPolygonRgn( LPPOINT /pPoints, LPINT lpPolyCounts, 
int nCount, int nPolyFillMode ); 


lpPoints 
Points to an array of POINT structures or an array of CPoint objects that de- 
fine the vertices of the polygons. Each polygon must be explicitly closed be- 
cause the system does not close them automatically. The polygons are specified 
consecutively. 


[pPolyCounts 
Points to an array of integers. The first integer specifies the number of vertices 
in the first polygon in the /pPoints array, the second integer specifies the num- 
ber of vertices in the second polygon, and so on. 


nCount 
Specifies the total number of integers in the /pPolyCounts array. 


nPolyFillMode 
Specifies the polygon-filling mode. This value may be either ALTERNATE or 
WINDING. 


Creates a region consisting of a series of closed polygons. The resulting region is 
stored in the CRgn object. 


The polygons may be disjoint or they may overlap. 


When the polygon-filling mode is ALTERNATE, the system fills the area be- 
tween odd-numbered and even-numbered polygon sides on each scan line. That is, 
the system fills the area between the first and second side, between the third and 
fourth side, and so on. 


When the polygon-filling mode is WINDING, the system uses the direction in 
which a figure was drawn to determine whether to fill an area. Each line segment 
in a polygon is drawn in either a clockwise or a counterclockwise direction. When- 
ever an imaginary line drawn from an enclosed area to the outside of a figure 
passes through a clockwise line segment, a count is incremented. When the line 
passes through a counterclockwise line segment, the count is decremented. The 
area is filled if the count is nonzero when the line reaches the outside of the figure. 


TRUE if the operation succeeded; otherwise FALSE. 


CRgn::CreatePolygonRgn, CDC::SetPolyFillMode, ::CreatePolyPolygonRgn 
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Syntax 


Parameters 


Remarks 
Return Value 


See Also 


Syntax 


Parameters 


Remarks 
Return Value 


See Also 


CRgn::CreateRectRgn 
BOOL CreateRectRegn( int x/, int y/, int x2, int y2 ); 


x1 
Specifies the x-coordinate of the upper-left corner of the region. 


yl 
Specifies the y-coordinate of the upper-left corner of the region. 


x2 
Specifies the x-coordinate of the lower-right corner of the region. 


y2 
Specifies the y-coordinate of the lower-right corner of the region. 
Creates a rectangular region that is stored in the CRgn object. 


TRUE if the operation succeeded; otherwise FALSE. 


CRegn::CreateRectRgnIndirect, CRgn::CreateRoundRectRgn, 
::CreateRectRgn 


CRgn::CreateRectRgnindirect 

BOOL CreateRectRgnIndirect( LPRECT /pRect ); 

lpRect 
Points to a RECT structure or CRect object that contains the coordinates of the 
upper-left and lower-right corners of the region. 

Creates a rectangular region that is stored in the CRgn object. 


TRUE if the operation succeeded; otherwise FALSE. 


CRegn::CreateRectRgn, CRgn::CreateRoundRectRgn, 
::CreateRectRgnIndirect 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 
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CRgn::CreateRoundRectRgn 


BOOL CreateRoundRectRegn( int x/, int y/, int x2, int y2, int x3, int y3 ); 


x1 
Specifies the x-coordinate of the upper-left corner of the region. 


yl 
Specifies the y-coordinate of the upper-left corner of the region. 


x2 
Specifies the x-coordinate of the lower-right corner of the region. 


y2 
Specifies the y-coordinate of the lower-right corner of the region. 


x3 
Specifies the width of the ellipse used to create the rounded corners. 


y3 
Specifies the height of the ellipse used to create the rounded corners. 


Creates a rectangular region with rounded corners that is stored in the CRgn 
object. 


TRUE if the operation succeeded; otherwise FALSE. 


CRegn::CreateRectRgn, CRgn::CreateRectRgnIndirect, 
::;<CreateRoundRectRgn 


CRgn::CRgn 
CRegnQ) ; 


Constructs a CRgn object. The m_ hObject data member does not contain a valid 
Windows GDI region until the object is initialized with one or more of the other 
CRgn member functions. 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


syntax 


Parameters 


Remarks 


Return Value 


CRgn::EqualRgn 
BOOL EqualRegen( CRgn* pRegn ) const; 


pkgn 
Identifies a region. 


Checks the given region to determine whether it is equivalent to the region stored 
in the CRgn object. 


TRUE if the two regions are equivalent; otherwise FALSE. 


::EqualRen 


CRgn::FromHandle 


static CRgn* FromHandle( HRGN /hRegn ); 


hRgn 
Specifies a handle to a Windows region. 


Returns a pointer to a CRgn object when given a handle to a Windows region. If a 
CRegn object is not already attached to the handle, a temporary CRgn object is 
created and attached. This temporary CRgn object is valid only until the next time 
the application has idle time in its event loop, at which time all temporary graphic 
objects are deleted. Another way of saying this is that the temporary object is only 
valid during the processing of one window message. 


A pointer to a CRgn object. If the function was not successful, the return value is 
NULL. 


syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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CRgn::GetRgnBox 


int GetRgnBox( LPRECT /pRect ) const; 

[pRect 
Points to a RECT structure or CRect object to receive the coordinates of the 
bounding rectangle. 


Retrieves the coordinates of the bounding rectangle of the CRgn object. 


Specifies the region’s type. It can be any of the following values: 


Value Meaning 

COMPLEXREGION Region has overlapping borders. 
NULLREGION Region is empty. 

ERROR CRgn object does not specify a valid region. 
SIMPLEREGION Region has no overlapping borders. 
::;GetRenBox 


CRgn::0ffsetRgn 


int OffsetRegn( int x, int y ); 
int OffsetRen( POINT point ); 


x 
Specifies the number of units to move left or right. 


Specifies the number of units to move up or down. 


point 
The x-coordinate of point specifies the number of units to move left or right. 
The y-coordinate of point specifies the number of units to move up or down. 
The point parameter may be either a POINT structure or a CPoint object. 


Moves the region stored in the CRgn object by the specified offsets. The function 
moves the region x units along the x-axis and y units along the y-axis. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Specifies the new region’s type. It can be any one of the following values: 


Value Meaning 

COMPLEXREGION _ Region has overlapping borders. 
ERROR Region handle is not valid. 
NULLREGION | Region is empty. 
SIMPLEREGION Region has no overlapping borders. 
::OffsetRen 


CRon::PtinRegion 


BOOL PtiInRegion( int x, int y ) const; 


BOOL PtInRegion( POINT point ) const; 


x 
Specifies the x-coordinate of the point to test. 


Specifies the y-coordinate of the point to test. 


point 
The x- and y-coordinate of point specify the x- and y-coordinate of the point to 
test the value of. The point parameter can either be a POINT structure or a 
CPoint object. 


Checks whether the point given by x and y is in the region stored in the CRgn 
object. 


TRUE if the point is in the region; otherwise FALSE. 


::PtInRegion 


Syntax 


Parameters 
Remarks 
Return Value 


See Also 


Syntax 


Parameters 
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CRgn::RectinRegion 
BOOL RectiInRegion( LPRECT /pRect ) const; 


lpRect 
Points to a RECT structure or CRect object. 


Determines whether any part of the rectangle specified by /pRect is within the 
boundaries of the region stored in the CRgn object. 


TRUE if any part of the specified rectangle lies within the boundaries of the re- 
gion; otherwise FALSE. 


::RectInRegion 


CRgn::SetRectRgn 


void SetRectRen( int x/, int y/, int x2, int y2 ); 
void SetRectRgn( LPRECT [pRect ); 


al, 
Specifies the x-coordinate of the upper-left corner of the rectangular region. 


yl 
Specifies the y-coordinate of the upper-left corner of the rectangular region. 


“2 
Specifies the x-coordinate of the lower-right corner of the rectangular region. 


y2 
Specifies the y-coordinate of the lower-right corner of the rectangular region. 
[pRect 


Specifies the rectangular region. Can be either a pointer to a RECT structure or 
a CRect object. 
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Remarks Creates a rectangular region. Unlike CreateRectRgn, however, it does not allo- 
cate any additional memory from the local Windows application heap. Instead, it 
uses the space allocated for the region stored in the CRgn object. This means that 
the CRgn object must already have been initialized with a valid Windows region 
before calling SetRectRgn. The points given by x/, y/, x2, and y2 specify the min- 
imum size of the allocated space. 


Use this function instead of the CreateRectRegn function to avoid calls to the local 
memory manager. 


See Also CRegn::CreateRectRgn, ::SetRectRgn 
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class CScrollBar : public CWnd 


See Also 


Public Members 


The CScrollBar class provides the functionality of a 
Windows scroll-bar control. 


CObject 
CScrollBar 


TE 


You create a scroll-bar control in two steps. First, 

call the constructor CScrollBar to construct the 
CScrollBar object, then call the Create member func- 
tion to create the scroll-bar control and attach it to the 
CScrollBar object. 


If you create a CScrollBar object within a dialog box (through a dialog resource), 
the CScrollBar is automatically destroyed when the user closes the dialog box. 


If you create a CScrollBar object within a window, you may also need to destroy 
it. If you create the CScrollBar object on the stack, it is destroyed automatically. 
If you create the CScrollBar object on the heap by using the new function, you 
must call delete on the object to destroy it when the user terminates the Windows 
scroll bar. 


If you allocate any memory in the CScrollBar object, override the CScrollBar de- 
structor to dispose of the allocations. 


CWnd, CButton, CComboBox, CEdit, CListBox, CStatic, CModalDialog, 
CDialog 


Construction/Destruction 


CScrollBar Constructs a CScrollBar object. 
Initialization 
Create Creates the Windows scroll bar and attaches it to 


the CScrollBar object. 
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Operations 
GetScrollPos 
SetScrollPos 
GetScrollRange 


SetScrollRange 


Retrieves the current position of a scroll box. 
Sets the current position of a scroll box. 


Retrieves the current minimum and maximum 
scroll-bar positions for the given scroll bar. 


Sets minimum and maximum position values for 
the given scroll bar. 


CScrollBar::Create 553 


Member Functions 


Syntax 


Remarks 


See Also 


syntax 


Parameters 


Remarks 


CScrollBar::CScrollBar 


CScrollBar(Q); 


Constructs a CScrollBar object. After constructing the object, call the Create 
member function to create and initialize the Windows scroll bar. 


CScrollBar::Create 


CScrollBar::Create 


BOOL Create( DWORD dwSpyle, const RECT& rect, CWnd* pParentWnd, 
UINT nID ); 


dwStyle 
Specifies the scroll bar’s style. 


rect 
Specifies the scroll bar’s size and position. Can be either a RECT structure or a 
CRect object. 


pParentWnd 
Specifies the scroll bar’s parent window, usually a CDialog or CModalDialog 
object. It must not be NULL. 


nID 
The scroll bar’s resource ID. 


You construct a CScrollBar object in two steps. First call the constructor, which 
constructs the CScrollBar object, then call Create, which creates and initializes 
the associated Windows scroll bar and attaches it to the CScrollBar object. 


Apply the following window styles to a scroll bar: 
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CScrollBar::Create 


Style Application 

WS_ CHILD Always. 

WS_ VISIBLE Usually. 

WS_DIABLED Rarely. 

WS_GROUP To group controls. 
WS_TABSTOP To allow tabbing to reach this 


scroll bar control. 


See CreateEx in the CWnd base class for a full description of these window 
styles. 


Use any combination of the following scroll bar styles for dwStyle: 


SBS_BOTTOMALIGN 
Used with the SBS_HORZ style. The bottom edge of the scroll bar is aligned 
with the bottom edge of the rectangle specified in Create. The scroll bar has 
the default height for system scroll bars. 


SBS_HORZ 
Designates a horizontal scroll bar. If neither the SBS_BOTTOMALIGN nor 
SBS_TOPALIGN style is specified, the scroll bar has the height, width, and 
position given in the Create member function. 


SBS_LEFTALIGN 
Used with the SBS_ VERT style. The left edge of the scroll bar is aligned with 
the left edge of the rectangle specified in the Create member function. The 
scroll bar has the default width for system scroll bars. 


SBS_RIGHTALIGN 
Used with the SBS_ VERT style. The right edge of the scroll bar is aligned 
with the right edge of the rectangle specified in the Create member function. 
The scroll bar has the default width for system scroll bars. 


SBS_SIZEBOX 
Designates a size box. If neither the 
SBS_SIZEBOXBOTTOMRIGHTALIGN nor 
SBS_SIZEBOXTOPLEFTALIGN style is specified, the size box has the 
height, width, and position given in the Create member function. 


SBS_SIZEBOXBOTTOMRIGHTALIGN 
Used with the SBS_SIZEBOX style. The lower-right corner of the size box is 
aligned with the lower-right corner of the rectangle specified in the Create 
member function. The size box has the default size for system size boxes. 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 
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SBS_SIZEBOXTOPLEFTALIGN 
Used with the SBS_SIZEBOX< style. The upper-left corner of the size box is 
aligned with the upper-left corner of the rectangle specified in the Create mem- 
ber function. The size box has the default size for system size boxes. 


SBS_TOPALIGN 
Used with the SBS_ HORZ style. The top edge of the scroll bar is aligned with 
the top edge of the rectangle specified in the Create member function. The 
scroll bar has the default height for system scroll bars. 


SBS_ VERT 
Designates a vertical scroll bar. If neither the SBS_ RIGHTALIGN nor 
SBS_LEFTALIGN style is specified, the scroll bar has the height, width, and 
position given in the Create member function. 

TRUE if successful; otherwise FALSE. 


CScrollBar::CScrollBar 


CScrollBar::GetScrollPos 


int GetScrollPos() const; 

Retrieves the current position of a scroll box. The current position is a relative 
value that depends on the current scrolling range. For example, if the scrolling 
range is 100 to 200 and the scroll box is in the middle of the bar, the current posi- 
tion is 150. 


Specifies the current position of the scroll box. 


CScrollBar::SetScrollPos, ::GetScrollPos 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CScrollBar::GetScrollRange 
void GetScrollRange( LPINT [pMinPos, LPINT /[pMaxPos ) const; 


[pMinPos 
Points to the integer variable that is to receive the minimum position. 


lpMaxPos 
Points to the integer variable that is to receive the maximum position. 


Copies the current minimum and maximum scroll-bar positions for the given 
scroll bar to the locations specified by JpMinPos and lpMaxPos. 


The default range for a scroll-bar control is empty (both values are 0). 


::GetScrollRange, CScrollBar::SetScrollRange 


CScrollBar::SetScrollPos 


int SetScrollPos( int nPos, BOOL bRedraw = TRUE ); 


nPos 
Specifies the new position for the scroll bar thumb. It must be within the scrol- 
ling range. 

bRedraw 
Specifies whether the scroll bar should be redrawn to reflect the new position. 


If bRedraw is TRUE, the scroll bar is redrawn. If itis FALSE, it is not red- 
rawn. The scroll bar is redrawn by default. 


Sets the current position of a scroll box to that specified by nPos and, if specified, 
redraws the scroll bar to reflect the new position. 


Set bRedraw to FALSE whenever the scroll bar will be redrawn by a subsequent 
call to another function to avoid having the scroll bar redrawn twice within a short 
interval. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


See Also 
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Specifies the previous position of the scroll box. 


CScrollBar::GetScrollPos, ::SetScrollPos 


CScrollBar::SetScrollRange 
void SetScrollRange( int nMinPos, int nMaxPos, BOOL bRedraw = TRUE ); 


nMinPos 
Specifies the minimum scrolling position. 


nMaxPos 
Specifies the maximum scrolling position. 


bRedraw 
Specifies whether the scroll bar should be redrawn to reflect the change. If 
bRedraw is TRUE, the scroll bar is redrawn; if FALSE, it is not redrawn. It is 
redrawn by default. 


Sets minimum and maximum position values for the given scroll bar. Set nMinPos 
and nMaxPos to 0 to hide or show standard scroll bars. 


Do not call this function to hide a scroll bar while processing a scroll-bar notifica- 
tion message. 


If a call to SetScrollRange immediately follows a call to the SetScrollPos mem- 
ber function, set bRedraw to SetScrollPos to 0 to prevent the scroll bar from being 
redrawn twice. 


The difference between the values specified by nMinPos and nMaxPos must not 
be greater than 32,767. 


CScrollBar::SetScrollPos, CScrollBar::GetScrollRange, ::SetScrollRange 
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class CSize : public tagSIZE 


The CSize class is similar to the Windows SIZE structure, which implements a 
relative coordinate or position. 


A SIZE structure has the following form: 
typedef struct tagSIZE { 
We. Cx; 


int cy; 
} SLE 


The ex and cy members of CSize are public. In addition, CSize implements mem- 
ber functions to manipulate the SIZE structure. 


Because CSize derives from tagSIZE, CSize objects may be used as SIZE 
structures. 


See Also CRect, CPoint 


Public Members 


Construction/Destruction 


CSize Constructs a CSize object. 

Operations 

operator == Checks for equality between CSize and a size. 
operator != Checks for inequality between CSize and a size. 
operator += Adds a size to CSize. 

operator —= Subtracts a size from CSize. 


Operators Returning CSize Values 
operator + Adds the two sizes. 


operator — Subtracts the two sizes. 


CSize::CSize 


Member Functions 


Syntax 


Parameters 


Remarks 


CSize::CSize 

CSizeQ; 

CSize( int initCX, int initCY ); 
CSize( SIZE initSize ); 


CSize( POINT initPt ); 
initCX 
Sets the ex member for the CSize. 
initCY 
Sets the cy member for the CSize. 
initSize 
Windows SIZE structure used to initialize CSize. 
initPt 
Windows POINT structure used to initialize CSize. 
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Constructs a CSize object. If no arguments are given, cx and cy members are not 


initialized. 
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Operators 


Syntax 


Parameters 


Remarks 


Return Value 


Syntax 


Parameters 


Remarks 


Return Value 


Syntax 


Parameters 


Remarks 


CSize::operator == 
BOOL operator ==( SIZE size ) const; 


SIZe 
A Windows SIZE structure. 


Checks for equality between two sizes. 


TRUE if the sizes are equal; otherwise FALSE. 


CSize::operator != 
BOOL operator !=( SIZE size ) const; 


SIZE 
A Windows SIZE structure. 


Checks for inequality between two sizes. 


TRUE if the sizes are not equal; otherwise FALSE. 


CSize::operator += 


void operator +=( SIZE size ); 


SIZE 
A Windows SIZE structure. 


Adds a size to a CSize. 


Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Return Value 


Syntax 


Parameters 


Return Value 


CSize::operator — 


CSize::operator -= 
void operator —=( SIZE size ); 


size 
A Windows SIZE structure. 


Subtracts a size from a CSize. 


CSize::operator + 


CSize operator +( SIZE size ) const; 


size 
A Windows SIZE structure. 


Returns a CSize that is the sum of two sizes. 


CSize::operator — 
CSize operator —( SIZE size ) const; 


SIZE 


A Windows SIZE structure. 


Returns a CSize that is the difference between two sizes. 
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CStatic 


class CStatic : public CWnd 


See Also 


Public Members 


The CStatic class provides the functionality of a 
Windows static control. A static control is a simple — 
text field, box, or rectangle that can be used to label, 
box, or separate other controls. A static control takes 
no input and provides no output. 


CStatic / 


You create a static control in two steps. First, call the 
constructor CStatic to construct the CStatic object, then call the Create member 
function to create the static control and attach it to the CStatic object. 


If you create a CStatic object within a dialog box (through a dialog resource), the 
CStatic object 1s automatically destructed when the user closes the dialog box. 


If you create a CStatic object within a window, you may also need to destroy it. A 
CStatic object created on the stack within a window is automatically destroyed. If 
you create the CStatic object on the heap by using the new function, you must call 
delete on the object to destroy it when the user terminates the Windows static 
control. 


CWnd, CButton, CComboBox, CEdit, CListBox, CScrollBar, CModalDialog, 
CDialog 


Construction/Destruction 


CStatic Constructs a CStatic object. 
Initialization 
Create Creates the Windows static control and attaches it 


to the CStatic object. 
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Member Functions 


CStatic::CStatic 


Syntax CStaticQ; 
Remarks Constructs a CStatic object. 
See Also CStatic::Create 


CStatic::Create 


syntax BOOL Create( const char FAR* /pText, DWORD dwStyle, const RECT& rect, 
CWnd* pParentWnd, UINT nID = Oxffff ); 


Parameters IpText 
Specifies the text to place in the control. If NULL, no text will be visible. 


dwStyle 
Specifies the static control’s window style. 


rect 
Specifies the position and size of the static control. It can be either a RECT 
structure or a CRect object. 


pParentWnd 
Specifies the CStatic parent window, usually a CDialog or CModalDialog 
object. It must not be NULL. 


nlD 
Specifies the static control’s resource ID. 


Remarks You construct a CStatic object in two steps. First call the constructor CStatic, 
then call Create, which creates the Windows static control and attaches it to the 
CStatic object. 
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CStatic::Create 


Apply the following window styles to a static control: 


Style 

WS_ CHILD 
WS_VISIBLE 
WS_DIABLED 


Application 
Always. 
Usually. 
Rarely. 


See CreateEx in the CWnd base class for a full description of these window 


styles. 


Use any combination of the following static control styles for dwStyle: 


Style 
SS_BLACKFRAME 


SS_BLACKRECT 


SS_ CENTER 


SS_GRAYFRA ME 


SS_ GRAYRECT 


SS_ICON 


Meaning 


Specifies a box with a frame drawn with the 
same color as window frames. The default is 
black. 


Specifies a rectangle filled with the color 
used to draw window frames. The default is 
black. 


Designates a simple rectangle and displays 
the given text centered in the rectangle. The 
text is formatted before it is displayed. 
Words that would extend past the end of a 
line are automatically wrapped to the 
beginning of the next centered line. 


Specifies a box with a frame drawn with the 
same color as the screen background 
(desktop). The default is gray. 


Specifies a rectangle filled with the color 
used to fill the screen background. The 
default is gray. 


Designates an icon displayed in the dialog 
box. The given text is the name of an icon 
(not a filename) defined elsewhere in the 
resource file. The n Width and nHeight 
parameters are ignored; the icon 
automatically sizes itself. 


Style 
SS_ LEFT 


SS_LEFTNOWORDWRAP 


SS_NOPREFIX 


SS_ RIGHT 


SS_ SIMPLE 


SS_USERITEM 
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Meaning 


Designates a simple rectangle and displays 
the given text flush-left in the rectangle. The 
text is formatted before it is displayed. 
Words that would extend past the end of a 
line are automatically wrapped to the 
beginning of the next flush-left line. 


Designates a simple rectangle and displays 
the given text flush-left in the rectangle. 
Tabs are expanded, but words are not 
wrapped. Text that extends past the end of a 
line is clipped. 


Unless this style is specified, Windows will 
interpret any ampersand (&) characters in 
the control’s text to be accelerator prefix 
characters. In this case, the ampersand (&) is 
removed and the next character in the string 
is underlined. If a static control is to contain 
text where this feature is not wanted, 
SS_NOPREFIX may be added. This static- 
control style may be included with any of 
the defined static controls. 


You can combine SS_NOPREFIX with 
other styles by using the bitwise-OR 
operator. This is most often used when 
filenames or other strings that may contain 
an ampersand (&) need to be displayed in a 
static control in a dialog box. 


Designates a simple rectangle and displays 
the given text flush-right in the rectangle. 
The text is formatted before it is displayed. 
Words that would extend past the end of a 
line are automatically wrapped to the 
beginning of the next flush-right line. 


Designates a simple rectangle and displays a 
single line of text flush-left in the rectangle. 
The line of text cannot be shortened or 
altered in any way. (The control’s parent 
window or dialog box must not process the 
WM_CTLCOLOR message.) 


Specifies a user-defined item. 
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Return Value 


See Also 


Style Meaning 


SS_ WHITEFRAME Specifies a box with a frame drawn with the 


same color as window backgrounds. The 
default is white. 


SS_ WHITERECT Specifies a rectangle filled with the color 
used to fill window backgrounds. The 
default is white. 


TRUE if successful; otherwise FALSE. 


CStatic::CStatic 
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class CStdioFile : public CFile 


A CStdioFile object represents a C run-time stream 
file as opened by the fopen function. Stream files are 
buffered and can be opened in either text mode (the 
default) or binary mode. 


Text mode provides special processing for carriage 

return—linefeed pairs. When you write a newline char- 

acter (OxOA) to a text-mode CStdioFile object, the byte pair (OxOA, OxOD) is sent 
to the file. When you read, the byte pair (OxOA, OxOD) is translated to a single 
OxOA byte. 


#include <afx.h> 


Comments The following CFile functions are not implemented for CStdioFile. 
=" Duplicate 
=» LockRange 
=" UnlockRange 


If you call these functions on a CStdioFile, you will get a 
CNotSupportedException. 


Public Members 


Data Members 


m_pStream A data member containing a pointer to an open file. 


Construction/Destruction 


CStdioFile Constructs a CStdioFile object from a path or file 
pointer. 

~CStdioFile Destroys the object and closes the file if it is open. 

Text Read/Write 

ReadString Reads a single line of text. 


WriteString Writes a single line of text. 
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Member Functions 


Syntax 


Parameters 


Remarks 


Example 


CStdioFile::CSidioFile 


CStdioFileQ; 
CStdioFile( FILE* pOpenStream ); 


CStdioFile( const char *pszFileName, UINT nOpenFlags ) 
throw( CFileException ); 


pOpenStream 
Specifies the file pointer returned by a call to the C run-time function fopen. 


pszFileName 
Specifies a string that is the path to the desired file. The path can be relative or 
absolute. 


nOpenFlags 
Specifies the action to take when the file is opened. You can combine options 
by using the bitwise-OR (| ) operator. One access permission and a text-binary 
specifier are required; the create and noInherit modes are optional. See 
CFile::CFile for a list of mode options. The share flags do not apply. 


The default version of the constructor works in conjunction with the CFile::Open 
member function to test errors. 


The one-parameter version constructs a CStdioFile object from a pointer to a file 
that is already open. Allowed pointer values include the predefined input/output 
file pointers stdin, stdout, or stderr. 


The two-parameter version constructs a CStdioFile object and opens the corre- 
sponding operating-system file with the given path. 


CFileException is thrown if the file cannot be opened or created. 


char* pFileName = "“test.dat"; 
CStdioFile fl; 
if( !f1.O0pen( pFileName, 
CFile::modeCreate | CFile::modeWrite | CFile::typeText ) ) { 
#ifdef _DEBUG 
afxDump << "Unable to open file" << "\\n"; 
dtendif 
exit 1); 
} 


CStdioFile f2( stdout ); 
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TRY 


CStdioFile f3( pFileName, 
CFile::modeCreate | CFile::modeWrite | CFile::typeText ); 


I 
CATCH( CFileException, e ) 
{ 
dFifdef _DEBUG 
afxDump << "File could not be opened ™ << e->m_cause << “\\n"; 
dtendi f 
i: 
END_ CATCH 


CStdioFile::~CStdioFile 


syntax virtual ~CStdioFile(); 


Remarks Usually, this destructor closes the operating-system file associated with the 
CStdioFile object. However, if the CStdioFile object was constructed by passing 
in a handle to an opened file using CStdioFile( int ), the operating-system file will 
not be closed. You must close the operating-system file yourself. 


CStdioFile::ReadString 


Syntax virtual char FAR* ReadString( char FAR* /psz, UINT nMax ) 
throw( CFileException ); 


Parameters [psz 
Specifies a pointer to a user-supplied buffer that will receive a null-terminated 
text string. 


nMax 
Specifies the maximum number of characters to read. Should be one less than 
the size of the /psz buffer. 


Remarks Reads text data into a buffer, up to a limit of nMax—1 characters, from the file as- 
sociated with the CStdioFile object. Reading is stopped by a carriage return— 
linefeed pair. If, in that case, fewer than nMax—1 characters have been read, a 
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Return Value 


Example 


Syntax 


Parameters 


Remarks 


Example 


newline character is stored in the buffer. A null character ('\O') is appended in 
either case. 


CFile::Read is also available for text-mode input, but it does not terminate on a 
carriage return—linefeed pair. 


The buffer containing the text data. 


extern CStdioFile f; 
char buf[l100]; 


f.ReadString( buf, 100 ); 


CStdioFile::WriteString 


virtual void WriteString( const char FAR* /psz ) 
throw( CFileException ); 


Ilpsz 
Specifies a pointer to a buffer containing a null-terminated text string. 


Writes data from a buffer to the file associated with the CStdioFile object. The ter- 
minating null character ('\O') is not written to the file. A newline character is writ- 
ten as a carriage return—linefeed pair. 


WriteString throws an exception in response to several conditions, including the 
disk-full condition. 


This is a text-oriented write function available only to CStdioFile and its descend- 
ents. CFile:: Write is also available, but rather than terminating on a null charac- 
ter, it writes the requested number of bytes to the file. 


extern CStdioFile f; 
char bufL] = “test string"; 


f.WriteString( buf ); 


CStdioFile::m_pStream —571 


Data Members 


CStdioFile::m_pStream 


syntax FILE* m_pStream; 


Remarks The m_pStream data member is the pointer to an open file as returned by the C 
run-time function fopen. It is NULL if the file has never been opened or has been 


closed. 
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class CString 


A CString object consists of a variable-length sequence of characters. The 
CString class provides a variety of functions and operators that manipulate 
CString objects using a syntax similar to that of Basic. Concatenation and com- 
parison operators, together with simplified memory management, make CString 
objects easier to use than ordinary character arrays. The increased processing over- 
head is not significant. The CString “Application Notes” section (starting on page 
598) offers useful information on: 


= CString Exception Cleanup 
=» CString Argument Passing 


Comments The maximum size of a CString object is MAXINT (32,767) characters. 


The const char* operator gives direct access to the characters in a CString object, 
which makes it look like a C-language character array. Unlike a character array, 
however, the CString class has a built-in memory-allocation capability. This al- 
lows string objects to grow as a result of concatenation operations. 


No attempt is made to “fold” CString objects (if you make two CString objects 
containing Chicago, for example, the characters in Chicago are stored in two 
places). 


The CString class is not implemented as a Microsoft Foundation collection class, 
although CString objects can certainly be stored as elements in collections. 


The overloaded const char* conversion operator allows CString objects to be 
freely substituted for character pointers in function calls. The CString( const 
char* psz ) constructor allows character pointers to be substituted for CString 
objects. 


Use the GetBuffer and ReleaseBuffer member functions when you need to 
directly access a CString as a nonconstant pointer to char (char* instead of a 
const char*). 


CString objects follow “value semantics.” A CString object represents a unique 
value. Think of a CString as an actual string not as a pointer to a string. 


Where possible, allocate CString objects on the frame rather than on the heap. 
This saves memory and simplifies parameter passing. 


#include <afx.h> 


Public Members 


Construction/Destruction 
CString 
~CString 


The String as an Array 
GetLength 


IsEmpty 
Empty 
GetAt 
operator [ | 
SetAt 


operator const char* () 
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Constructs CString objects in various ways. 


Destroys a CString object. 


Returns the number of characters in a CString 
object. 


Tests whether the length of a CString object is 0. 
Forces a string to have 0 length. 

Returns the character at a given position. 

Returns the character at a given position. 

Sets a character at a given position. 


Directly accesses characters stored in a CString 
object. 


Assignment/Concatenation 


operator = 
operator + 


operator += 


Comparison 
operator ==, <, etc. 
Compare 
CompareNoCase 
Collate 


Assigns a new value to a CString object. 
Concatenates two strings and returns a new string. 


Concatenates a new string to the end of an existing 
string. 


Comparison operators (ASCII, case sensitive). 
Compares two strings (ASCII, case sensitive). 
Compares two strings (ASCII, case insensitive). 


Compares two strings with proper language- 
dependent ordering. 


o/4 


CString 


Extraction 
Mid 


Left 
Right 
SpanIncluding 


SpanExcluding 


Other Conversions 
MakeUpper 


MakeLower 


MakeReverse 


Searching 
Find 


ReverseFind 


FindOneOf 


Archive/Dump 


operator << 


operator >> 


Buffer Access 


GetBuffer 


GetBufferSetLength 


ReleaseBuffer 


Extracts the middle part of a string (like the Basic 
MID$ command). 


Extracts the left part of a string (like the Basic 
LEFT$ command). 


Extracts the right part of a string (like the Basic 
RIGHT$ command). 


Extracts a substring that contains only the charac- 
ters in a set. 


Extracts a substring that contains only the charac- 
ters not in a set. 


Converts all the characters in this string to upper- 
case characters. 


Converts all the characters in this string to lower- 
case characters. 


Reverses the characters in this string. 


Finds a character or substring inside a larger string. 


Finds a character inside a larger string; starts from 
the end. 


Finds the first matching character from a set. 


Inserts a CString object to an archive or dump 
context. 


Extracts a CString object from an archive. 


Returns a pointer to the characters in the CString. 


Returns a pointer to the characters in the CString, 
truncating to the specified length. 


Yields control of the buffer returned by GetBuffer. 


CString = 575 


Windows-Specific 


LoadString Loads an existing CString object from a Windows 
resource. 

AnsiToOem Makes an in-place conversion from the ANSI char- 
acter set to the OEM character set. 

OemToAnsi Makes an in-place conversion from the OEM char- 


acter set to the ANSI character set. 
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Member Functions 


Syntax 


Remarks 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


CString::Ansifo0em 
void AnsiToOem(); 


Converts all the characters in this CString object from the ANSI character set to 
the OEM character set. See the IBM PC Extended Character Set table and the 
ANSI table in the Microsoft Windows Programmer’s Reference. 


This function is available only in the Windows compiled version of the Microsoft 
Foundation Class Library, and it is declared in AFX.H only if WINDOWS is 
defined. 


CString s( '\\265' ); // Octal ANSI code for '1/2' 
s.AnsiToOem(); 
ASSERT( s == "\\253" ); // Octal oem code for ‘'1/2' 


CString::OemToAnsi 


CString::Collate 


int Collate( const char* psz ) const; 


PSZ 


The other string used for comparison. 


Performs a locale-specific comparison of two strings; uses the run-time function 
strcoll. Compare performs a faster, ASCI]-only comparison. 


A CString object can be used as the argument because the class provides the ap- 
propriate conversion operator. 


Q The strings are identical. 
-1 This CString object is less than psz. 
1 This CString object is greater than psz. 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


Syntax 


Parameters 


CString::CompareNoCase = 577 


CString sl( "abc" ); 
CString s2( "abd" ); 
ASSERT( s1.Collate( s2 ) == -1 ); 


CString::Compare, CString::CompareNoCase 


CString::Compare 
int Compare( const char* psz ) const; 


Psz 
The other string used for comparison. 


Compares this CString object with another string, character by character; uses the 
run-time function stremp. If you need a language-specific comparison, use the 
Collate member function. 

0 The strings are identical. 
—1 This CString object is less than psz. 


1 This CString object is greater than psz. 


CString s1( "abc" ); 

CString s2( "abd" ); 

ASSERT( s1.Compare( s2 ) == -1 ); // Compare with another CString 
ASSERT( s1.Compare( “abe" ) == -1 ); // Compare with a char * string 


CString:: CompareNoCase, CString::Collate 


CString::CompareNoCase 


int CompareNoCase( const char* psz ) const; 


psz 
The other string used for comparison. 
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Remarks 


Return Value 


Example 


See Also 


Syntax 


Compares this CString object with another string, character by character; uses the 
run-time function stricmp. The algorithm for deciding case applies only to ASCII 
characters:('A' == 'a' —>'Z' == 'z'). 


If you need a language-specific comparison, use the Collate member function. 


Q The strings are identical (ignoring case). 
—1 This CString object is less than psz (ignoring case). 
1 This CString object is greater than psz (ignoring case). 


CString si€ “abe” 3: 

CString s2( "ABD" ); 

ASSERT( s1.CompareNoCase( s2 ) == -1 ); // Compare with a CString 
ASSERT( s1.Compare( "ABE" ) == -1 ); // Compare with a char * string 


CString::Compare, CString::Collate 


CString::CString 
CString(); 


CString(const CString& stringSrc ) 
throw( CMemoryException ); 


CString( const char* psz ) 
throw( CMemoryException ); 


CString( char ch, int nRepeat = 1 ) 
throw( CMemoryException ); 


CString( const char* pch, int nLength ) 
throw( CMemoryException ); 


CString( const char FAR* [psz ) 
throw( CMemoryException ); 


CString( const char FAR®* Ipch, int nLength ) 
throw( CMemoryException ); 


Parameters 


Remarks 


Example 


See Also 
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stringSrc 
An existing CString object to be copied into this CString object. 


PSZ 
A null-terminated string to be copied into this CString object. 


ch 
A single character to be repeated nRepeat times. 


nRepeat 
The repeat count for ch. 


pch 
A pointer to an array of characters of length nLength, not null-terminated. 


nLength 
A count of the number of characters in pch. 


Ipsz 
A far pointer to a null-terminated ASCII string. 


lpch 
A far pointer to an array of characters of length nLength. 


Each of these constructors initializes a new CString object with the specified data. 


Because the constructors copy the input data into new allocated storage, you 
should be aware that memory exceptions may result. 


Note that some of these constructors act as ““conversion functions.” This allows 
you to substitute, for example, a char* where a CString object is expected. 


CString sl; // Empty string 

CString s2¢ “cat” >); // From aC string literal 
CString s3 = s2; // Copy constructor 

CString s4( s2+" "+ s3 ); // From a string expression 
CString ss¢ 7x" 2s fd So = “ye 

CSUPING. SOC “Ky. 16. 9% ET $6. SU RXKKKX” 


CString city = "Philadelphia"; // NOT the assignment operator 


CString: : operator =, “CString Exception Cleanup” on page 598 
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CString::~CString 


Syntax — ~CString(); 
Remarks. This CString destructor releases allocated memory used to store the string’s char- 
acter data. | 


CString::Empty 


Syntax void Empty(); 
Remarks _ Makes this CString object an empty string, and frees memory as appropriate. 
Example CString s1( "abc" ); 

CString s2; 

sl.Empty(); 


ASSERT( sl == S2 ); 


See Also” CString::IsEmpty, “CString Exception Cleanup” on page 598 


CString::Find 
Syntax int Find( char ch ) const; 


int Find( const char* pszSub ) const; 


Parameters ch 
A single character to search for. 


pszSub 
A substring to search for. 


Remarks Searches this string for the first match of a substring. The function is overloaded to 
accept both single characters (similar to the run-time function strchr) and strings 
(similar to strstr). 


Return Value 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


Syntax 


Parameters 


CString::GetAt 581 


The zero-based index of the first character in this CString object that matches the 
requested substring or characters; —1 if the substring or character is not found. 


CString s( “abcdef™ ); 
ASSERT( s.Find( 'c' ) == 2 ); 
ASSERT( s.Find( "de" ) == 3); 


CString::ReverseFind, CString::FindOneOf 


CString::FindOneOf 


int FindOneOf( const char* pszCharSet ) const; 


pszCharSet 
String containing characters for matching. 


Searches this string for the first character that matches any character contained in 
pszCharSet. 


The zero-based index of the first character in this string that is also in pszCharSet; 
—1 if there is no match. 


CString s( “abcdef" ); 
ASSERT( s.FindOneOf( "xd" ) == 3 ); // ‘d' is first match 


CString::Find 


CString::GetAt 
char GetAt( int n/ndex ) const; 


nIndex 
Zero-based index of the character in the CString object. The nJndex parameter 
must be greater than or equal to 0 and less than GetLength(). The Debug ver- 
sion of the Microsoft Foundation Class Library validates the bounds of nIndex; 
the Release version will not. 
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Remarks You can think of a CString object as an array of characters. The GetAt member 
function returns a single character specified by an index number. The overloaded 
subscript ([ ]) operator is a convenient alias for GetAt. 


Return Value A char containing the character at the specified position in the string. 
Example CString s( "“abcdef" ); 

ASSERT( s.GetAt(2) == 'c' ); 
See Also CString::SetAt, CString::GetLength, CString::operator [ | 


CString::GetBuffer 


Syntax char* GetBuffer( int nMinBufLength ) 
throw( CMemoryException ); 


Parameters nMinBufLength 
The minimum size of the CString character buffer in bytes. You do not need to 
allow space for a null terminator. 


Remarks Returns a pointer to the internal character buffer for the CString object. The re- 
turned pointer to char is not const and thus allows direct modification of CString 
contents. 


If you use the pointer returned by GetBuffer to change the string contents, you 
must call ReleaseBuffer before using any other CString member functions. 


The address returned by GetBuffer is invalid after the call to ReleaseBuffer or 
any other CString operation. 


The buffer memory will be freed automatically when the CString object is de- 
stroyed. 


Note If you keep track of the string length yourself, you need not append the ter- 
minating null byte. You must, however, specify the final string length when you 
release the buffer with ReleaseBuffer, or you can pass —1 for the length and 
ReleaseBuffer will perform a strlen on the buffer to determine its length. 


Return Value _ Achar pointer to the object’s (usually null-terminated) ASCII character buffer. 


Example 


See Also 


Syntax 


Parameters 


Remarks 


CString::GetBufferSetLength 583 


CString s; 

char* p = s.GetBuffer(10); // Allocate space for 1@ characters 

s = “abcdefg"; // p is still valid because length of s is 7 

characters 

Di) ="B"s 77 Change b™ “to "BB" 
#Hifdef _ DEBUG 

afxDump << "char* p " << (void*) p << "3" << p <K “"A\An"; 
dFendi f 

char* q = s.GetBuffer(12); // Get a new, larger buffer 

// q is a different address than p, but the string is the same. 
#Hifdef _DEBUG 

afxDump << "“char* q " << (void*) q << "3" << q << “A\\n"; 
#tendif 

s t= "hij"; // String length is still smaller than 12 
ifdef _DEBUG 


afxDump << "“char* q " << (void*) q <K ":" << q << “A\\n"; 
dtendif 
s += "kilmnop"; // Now it is larger than 12, so the characters 


// Are moved, and q is no longer valid 
dFifdef _DEBUG 


afxDump << "“char* q " << (void*) gq <K ":" << q << “"\An"; 
afxDump << "CString s " << s << “"\\n"; // S contains 
"aBcdefghijkIlmnop” 
#fendi f 


s.ReleaseBuffer(); 


CString::GetBufferSetLength, CString::ReleaseBuffer 


CString::GetBufferSetLength 


char* GetBufferSetLength( int nNewLength ) 
throw( CMemoryException ); 


nNewLength 
The exact size of the CString character buffer in bytes. 


Returns a pointer to the internal character buffer for the CString object, truncating 
or growing its length if necessary to exactly match the length specified in 
nNewLength. The returned pointer to char is not const and thus allows direct 
modification of CString contents. 


If you use the pointer returned by GetBuffer to change the string contents, you 
must call ReleaseBuffer before using any other CString member functions. 
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Return Value 


See Also 


Syntax 


Remarks 


Example 


See Also 


Syntax 
Remarks 


Return Value 


The address returned by GetBuffer is invalid after the call to ReleaseBuffer or 
any other CString operation. 


The buffer memory will be freed automatically when the CString object is 
destroyed. 


Note If you keep track of the string length yourself, you need not append the ter- 
minating null byte. You must, however, specify the final string length when you 
release the buffer with ReleaseBuffer, or you can pass —1 for the length and 
ReleaseBuffer will perform a strlen on the buffer to determine its length. 


A char pointer to the object’s (usually null-terminated) ASCH character buffer. 


CString::GetBuffer, CString::ReleaseBuffer 


CString::GetLength 
int GetLengthQ const; 


Returns a count of the characters in this CString object. The count does not in- 
clude a null terminator. 


CString s( "“abcdef" ); 
ASSERT( s.GetLength() == 6 ); 


CString:: IsEmpty 


CString::lsEmpty 


BOOL IsEmpty() const; 
Tests a CString object for the empty condition. 


TRUE if the CString object has 0 length; otherwise FALSE. 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


Syntax 


Parameters 


CString::LoadString 585 


CString s; 
ASSERT( s.IsEmpty() ); 


CString::GetLength 


CString::Left 


CString Left( int nCount ) const 
throw( CMemoryException ); 


nCount 
The number of characters to extract from this CString object. 


Extracts the first (that is, leftmost) nCount characters from this CString object and 


returns a copy of the extracted substring. If nCount exceeds the string length, then 
the entire string is extracted. 


Left is similar to the Basic LEFT$ command (except that indexes are zero-based). 


A CString object containing a copy of the specified range of characters. 


Note The returned CString object may be empty. 


CString s( “abcdef" ); 
ASSERT( s.Left(3) == "abc" ); 


CString::Mid, CString::Right 


CString::LoadString 


BOOL LoadString( UINT nJD ) 
throw( CMemoryException ); 


nlID 
A Windows string resource ID. 
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Remarks 


Return Value 


Example 


Syntax 
Remarks 


Example 


See Also 


syntax 
Remarks 


Example 


Reads a Windows string resource, identified by n/D, into an existing CString ob- 
ject. The maximum string size is 255 characters. 


This function is declared in AFX.H only if _. WINDOWS is defined. Its use re- 
quires the Windows compiled version of the Microsoft Foundation classes, and it 
is normally used with AFX WIN.H. 

TRUE if resource load was successful; otherwise FALSE. 


define IDS FILENOTFOUND 1 
CString s; 
s.LoadString( IDS _FILENOTFOUND ); 


CString::MakeLower 
void MakeLower(); 
Converts this CString object to a lowercase string. 


CString s( "ABC" ); 
s.MakeLower(); 
ASSERT( Ss == "abc" ); 


CString::MakeUpper 


CString::MakeReverse 
void MakeReverse(); 
Reverses the order of the characters in this CString object. 


CString s( “abc" ); 
s.MakeReverse(); 
ASSERT( s == "cba" ); 


Syntax 
Remarks 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


CString::Mid 


CString::MakeUpper 
void MakeUpper(); 
Converts this CString object to an uppercase string. 


CString s( “abc"™ ); 
s.MakeUpper(); 
ASSERT( s == "ABC" ); 


CString::MakeLower 


CString::Mid 


CString Mid( int nFirst ) const 
throw( CMemoryException ); 


CString Mid( int nFirst, int nCount ) const 
throw( CMemoryException ); 


nFirst 


087 


The zero-based index of the first character in this CString object that is to be in- 


cluded in the extracted substring. 


nCount 


The number of characters to extract from this CString object. If this parameter 


is not supplied, then the remainder of the string is extracted. 


Extracts a substring of length nCount characters from this CString object, starting 


at position nFirst (zero-based). The function returns a copy of the extracted sub- 


string. 


Mid is similar to the Basic MID$ command (except that indexes are zero-based). 


A CString object that contains a copy of the specified range of characters. 


Note The returned CString object may be empty. 
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Example CString s( "abcdef" ); 
ASSERT( s.Mid( 2, 3 ) == "cde" ); 
See Also CString::Left, CString::Right 


CString::0emToAnsi 


Syntax void OemToAnsi(); 


Remarks Converts all the characters in this CString object from the OEM character set to 
. the ANSI character set. See the IBM PC Extended Character Set table and the 
ANSI table in the Microsoft Windows Programmer’s Reference. 


This function is available only in the Windows compiled library of the Microsoft 
Foundation classes and is declared in AFX.H only if _WINDOWS is defined. 


Example CString s( '\\253' ); // Octal oem code for '1/2' 
s.OemToAnsi(); 
ASSERT( s == "\\265" ); // Octal ANSI code for ‘1/2’ 
See Also CString::AnsiToOem 


CString::ReleaseBuffer 


Syntax void ReleaseBuffer( int nNewLength =-1 ); 


Parameters nNewLength 
The new length of the string in characters, not counting a null terminator. If the 
string is null-terminated, the —1 default value sets the CString size to the cur- 
rent length of the string. 


Remarks Use ReleaseBuffer to end use of a buffer allocated by GetBuffer. 


If you know that the string in the buffer is null-terminated, you can omit the 
nNewLength argument. If your string 1s not null-terminated, then use nNewLength 
to specify its length. 


Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Example 


See Also 


Syntax 


Parameters 


CString::Right 589 
The address returned by GetBuffer is invalid after the call to ReleaseBuffer or 


any other CString operation. 


CString s; 

char* p = s.GetBuffer( 1024 ); 

S = “apc”: 

ASSERT( s.GetLength() == 3 ); // String length = 3 
s.ReleaseBuffer(); // Surplus memory released, p is now invalid 
ASSERT( s.GetLength() == 3 ); // Length still 3 


CString::GetBuffer 


CString::ReverseFind 


int ReverseFind( char ch ) const; 


ch 
The character to search for. 


Searches this CString object for the last match of a substring. The function 1s simi- 
lar to the run-time function strrehr. 


The index of the last character in this CString object that matches the requested 
character; —1 if the character is not found. 


CString s( "“abcabc" ); 
ASSERT( s.ReverseFind( 'b' ) == 4 ); 


CString::Find, CString::FindOneOf 


CString::Right 


CString Right( int nCount ) const 
throw( CMemoryException ); 


nCount 


The number of characters to extract from this CString object. 
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Remarks 


Return Value 


Example 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


Extracts the last (that is, rightmost) nCount characters from this CString object 
and returns a copy of the extracted substring. If nCount exceeds the string length, 
then the entire string is extracted. 


Right is similar to the Basic RIGHT$ command (except that indexes are zero- 
based). 


A CString object that contains a copy of the specified range of characters. 


Note The returned CString object may be empty. 


CString s( “abcdef" ); 
ASSERT( s.Right(3) == "def" ): 


CString::Mid, CString::Left 


CString::SetAt 
void SetAt( int n/ndex, char ch ); 


nIndex 
Zero-based index of the character in the CString object. The nJndex parameter 
must be greater than or equal to 0 and less than GetLength. The Debug version © 
of the Microsoft Foundation classes will validate the bounds of nIndex; the 
Release version will not. 


ch 
The character to insert. Must not be '\O'. 


You can think of a CString object as an array of characters. The SetAt member 
function overwrites a single character specified by an index number. SetAt will 


not enlarge the string if the index exceeds the bounds of the existing string. 


CString::GetAt, CString::operator [ | 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CString::Spanincluding 591 


CString::SpanExcluding 


CString SpanExcluding( const char* pszCharSet ) const 
throw( CMemoryException ); 


pszCharSet 
A string interpreted as a set of characters. 


Extracts the largest substring that excludes only the characters in the specified set 
pszCharSet; starts from the first character in this CString object. 


If the first character of the string is included in the character set, then 
SpanExcluding returns an empty string. 


A copy of the substring that contains only characters not in pszCharSet. 


CString::SpanIncluding 


CString::Spanincluding 


CString SpanIncluding( const char* pszCharSet ) const 
throw( CMemoryException ); 


pszCharSet 
A string interpreted as a set of characters. 


Extracts the largest substring that contains only the characters in the specified set 
pszCharSet, starts from the first character in this CString object. 


If the first character of the string is not in the character set, then SpanIncluding re- 
turns an empty string. 


A copy of the substring that contains only characters in pszCharSet. 


CString::SpanExcluding 
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Operators 


Syntax 


Remarks 


Example 


See Also 


Syntax 


Remarks 


CString::operator = 


const CString& operator =( const CString& stringSrc ) 
throw( CMemoryException ); 


const CString & operator =( const char* psz ) 
throw( CMemoryException ); 


const CString& operator =( char ch ) 
throw( CMemoryException ); 


The CString assignment operator (=) reinitializes an existing CString object with 
new data. If the destination string (that is, the left side) is already large enough to 
store the new data, no new memory allocation is performed. 


You should be aware that memory exceptions may occur whenever you use the as- 
signment operator because new storage is often allocated to hold the resulting 
CString object. 


CString sl, s2; // Empty CString objects 

Ch eS “teats if Sk = “Cate 

s2 = sl; // sl and s2 each = "cat" 

sl = “the +A sls // Or expressions 

Sip et “EK // Or just individual characters 
CString:: CString 


CSiring::operator const char* () 


operator const char* () const; 


This useful casting operator provides an efficient method to access the null- 
terminated C string contained in a CString object. No characters are copied; only 
a pointer is returned. 


Return Value 


Syntax 


Remarks 


Example 


CString::operators <<,>> 593 


Be careful with this operator. If you change a CString object after you have ob- 
tained the character pointer, you may cause a reallocation of memory that invali- 
dates the pointer. 


A character pointer if the cast was successful; otherwise a null pointer. 


CString::operators <<, >> 


friend CArchive& operator <<( CArchive& ar, const CString& string ); 
throw(CArchiveException); 


friend CArchive& operator >>( CArchive& ar, CString& string ); 
throw(CArchiveException); 


friend CDumpContext& operator <<( CDumpContext& dc, 
const CString& string ); 


The CString insert (<<) operator supports diagnostic dumping and storing to an 
archive. The extract (>>) operator supports loading from an archive. 


The CDumpContext operators are valid only in the Debug version of the 
Microsoft Foundation Class Library. 


// Operator << >> example 
extern CArchive ar; 
CString s( "abc" ); 
#Fifdef _ DEBUG 
afxDump << s; // Prints the value (abc) 
afxDump << &s; // Prints the address 


dtendif 
if( ar.IsLoading() ) 
ar >> Ss; 
else 


ar SS. -Ss 
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Syntax 


Remarks 


Return Value 


Example 


See Also 


CString::operator + 


friend CString operator +( const CString& string/, const CString& string2 ) 
throw( CMemoryException ); 


friend CString operator +( const CString& string, char ch ) 
throw( CMemoryException ); 


friend CString operator +( char ch, const CString& string ) 
throw( CMemoryException ); 


friend CString operator +( const CString& string, const char* psz ) 
throw( CMemoryException ); 


friend CString operator +( const char* psz, const CString& string ) 
throw( CMemoryException ); 


The + concatenation operator joins two strings and returns a CString object. One 
of the two argument strings must be a CString object. The other can be a charac- 
ter pointer or a character. 


You should be aware that memory exceptions may occur whenever you use the 
concatenation operator since new storage may be allocated to hold temporary data. 


You must ensure that the maximum length limit is not exceeded. The Debug ver- 
sion of the Microsoft Foundation Class Library asserts when it detects strings that 
are too long. 


A CString object that is the temporary result of the concatenation. This return 
value makes it possible to combine several concatenations in the same expression. 


CString sl( “abc"™ ); 
CString s2( “def" ); 
ASSERT( (sl + s2 ) == "abcdef" ); 


CString s3; 


$3 = CString( "abc" ) + "def" ; // Correct 
// s3 = “abc" + "def"; // Wrong! One of the arguments must be a CString 


CString: :operator += 


CString::operator+= 595 


CString::operator += 


Syntax void operator +=( const CString& string ) 
throw( CMemoryException ); 


void operator +=( char ch ) 
throw( CMemoryException ); 


void operator +=( const char* psz ) 
throw( CMemoryException ); 


Remarks The += concatenation operator joins characters to the end of this string. The opera- 
tor accepts another CString object, a character pointer, or a single character. 


You should be aware that memory exceptions may occur whenever you use this 
concatenation operator because new storage may be allocated for characters added 
to this CString object. 


You must ensure that the maximum length limit is not exceeded. The Debug ver- 


sion of the Microsoft Foundation Class Library asserts when it detects strings that 
are too long. 


Example CString s( "abc" ); 
ASSERT( ( s += "def" ) == “abcdef" ); 


See Also CString::operator + 


596 CString Comparison Operators 


Syntax 


Remarks 


CString Comparison Operators 


BOOL operator ==( const CString& s/, const CString& s2 ); 
BOOL operator ==( const CString& s/, const char* s2 ); 
BOOL operator ==( const char* s/, const CString& s2 ); 
BOOL operator !=( const CString& s/, const CString& s2 ); 
BOOL operator !=( const CString& s/, const char* s2 ); 
BOOL operator !=( const char* s/, const CString& s2 ); 
BOOL operator <( const CString& s/, const CString& s2 ); 
BOOL operator <( const CString& s/, const char* s2 ); 
BOOL operator <( const char* s/, const CString& s2 ); 
BOOL operator >( const CString& s/, const CString& s2 ); 
BOOL operator >( const CString& s/, const char* s2 ); 
BOOL operator >( const char* s/, const CString& s2 ); 
BOOL operator <=( const CString& s/, const CString& s2 ); 
BOOL operator <=( const CString& s/, const char* s2 ); 
BOOL operator <=( const char* s/, const CString& s2 ); 
BOOL operator >=( const CString& s/, const CString& s2 ); 
BOOL operator >=( const CString& s/, const char* s2 ); 


BOOL operator >=( const char* s/, const CString& s2 ) ; 


These comparison operators compare two CString objects, and they compare a 
CString object with an ordinary null-terminated C string. The operators are a con- 
venient substitute for the case-sensitive Compare member function. 


Return Value 


Example 


Syntax 


Remarks 


Example 


See Also 


CString::operator[] 597 


TRUE if the strings meet the comparison condition; otherwise FALSE. 


CString sl( "abc" ); 

CString s2( "abd" ); 

ASSERT( sl < s2 ); // Operator is overloaded for both 
ASSERT( "ABC" < sl ); // CString and charx 

ASSERT( s2 > “abe" ); 


CString::operator [ | 


char operator [ ]( int n/ndex ) const; 


You can think of a CString object as an array of characters. The subscript ([ ]) 
operator returns a single character specified by the zero-base index in nIndex. This 
operator is a convenient substitute for the GetAt member function. 


You can use the subscript ({ ]) operator on the right side of an expression (r-value 
semantics), but you cannot use it on the left side of an expression (l-value seman- 
tics). That is, you can use this operator to get characters in a CString, but you can- 
not use it to set characters in the CString. 


CString s( “abc"™ ); 
ASSERTG -S~L] = "bs 


CString::GetAt, CString::SetAt 
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Application Notes 


Memory Leaks 


Example 


CString Exception Cleanup 


If you notice that the Microsoft Foundation diagnostic memory allocator is re- 
porting leaks for non-CObject memory blocks, check your exception-processing 
logic to see if CString objects are being cleaned up properly. 


The CString class is typical in that its constructor and member functions allocate 
memory that must be freed by the destructor. CString is unique, however, in that 
instances are often allocated on the frame rather than on the heap. When a frame- 
allocated CString object goes out of scope, its destructor is called “invisibly” 
without need for a delete statement. 


Whether you explicitly destroy an object or not, you must be sure that the destruc- 


tor call isn’t bypassed by uncaught exceptions. For frame-allocated (and heap- 
allocated) CString objects, use a CATCH statement to channel execution through 
the end of the function that contains the CString allocation. 


This is an example of incorrect programming. 


void TestFunctioni() 


{ 
CString sl = "test"; 
OtherFunction(); // OtherFunction may raise an exception 
// This point not passed if an exception occurred. 
// si's destructor called here (frees character storage for 
"test") 
} 


You must add TRY/CATCH code to free the string character data in response to 
memory exceptions. 
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Now the program has been improved to properly handle exceptions. 


void TestFunction2() 
v 

CString si; 

TRY 


{ 
sl = "test"; 
OtherFunction(); // OtherFunction may raise an exception 


} 

CATCH( CException, e ) 

{ 
sl.Empty(); // Frees up associated data 
THROW_LAST() 


} 
END_ CATCH 


CString Argument Passing 


Argument-Passing Conventions 


When you define a class interface, you must determine the argument-passing con- 
vention for your member functions. There are some standard rules for passing and 
returning CString objects. If you follow these rules, you will have efficient, cor- 
rect code. 


Strings as Function Inputs 


If a string is an input to a function, in most cases it is best to declare the string 
function parameter as const char*. Convert to CString object as necessary within 
the function, using constructors and assignment operators. If the string contents 
are to be changed by a function, declare the parameter as a nonconstant CString 
reference (CString&). 
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Strings as Function Outputs 


Normally you can return CString objects from functions since CStrings follow 
value semantics like primitive types. To return a read-only string, use a constant 
CString reference (const CString &). 


Example class CName : public CObject 
{ 
private: 
CString m_firstName; 
char m_middlelnit; 
CString m_lastName; 


public: 
CName() {} 
void SetData( const char* fn, const char mi, const char* In ) 
{ 
m_firstName = fn; 
m_middleInit = mi; 
m_lastName = In; 
} 
void GetData( CString& cfn, char mi, CString& clin ) 
{ 
cfn = m_firstName; 
mi = m_middlelnit; 
cln = m_lastName; 
} 
CString GetLastName() 
{ 
return m_lastName; 
} 
ae 


CName name; 
CString last, first; 
char middle; 


name.SetData( "John", 'Q', "Public" ); 


ASSERT( name.GetLastName() == "Public" ); 
name.GetData( first, middle, last ); 
ASSERT( ( first == "John" ) && ( last == "Public" ) ); 
} 
return @; 


} 
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class CStringArray : public CObject 


The CStringArray class supports arrays of CString 
objects. 


The member functions of CStringArray are similar 
to the member functions of class CObArray. Be- 
cause of this similarity, you can use the CObArray reference documentation for 
member function specifics. Wherever you see a CObject pointer as a return value, 
substitute a CString. Wherever you see a CObject pointer as a function parame- 
ter, substitute a const pointer to char. 


CObject* CObArray::GetAt( int <nIndex> ) const; 


for example, translates to 


CString CStringArray::GetAt( int <nIndex> ) const; 


and 


void SetAt( int <nIndex>, CObject* <newElement> ) 


translates to 


void SetAt( int <nIndex>, const char* <newElement> ) 


CStringArray incorporates the IMPLEMENT_SERIAL macro to support 
serialization and dumping of its elements. If an array of CStrings is stored to an 
archive, either with the overloaded insertion operator or with the Serialize mem- 
ber function, each element 1s, in turn, serialized. 


If you need a dump of individual string elements in the array, you must set the 
depth of the dump context to 1 or greater. 


When a CString array is deleted, or when its elements are removed, string 
memory is freed as appropriate. 


#include <afxcoll.h> 


Public Members 


Construction/Destruction 
CStringArray Constructs an empty array for CString objects. 
~CStringArray Destroys a CStringArray object. 


CStringArray 


Bounds 
GetSize 
GetUpperBound 
SetSize 


Operations 
FreeExtra 


RemoveAll 


Element Access 
GetAt 
SetAt 


ElementAt 


Growing the Array 
SetAtGrow 


Add 


Insertion/Removal 
InsertAt 


RemoveAt 


Operators 
operator [ | 


Gets number of elements in this array. 
Returns the largest valid index. 


Sets the number of elements to be contained in this 
array. 


Frees all unused memory above the current upper 
bound. 


Removes all the elements from this array. 


Returns the value at a given index. 


Sets the value for a given index; array not allowed 
to grow. 


Returns a temporary reference to the element 
pointer within the array. 


Sets the value for a given index, growing the array 
if necessary. 


Adds an element to the end of the array; grows the 
array if necessary. 


Inserts an element (or all the elements in another 
array) at a specified index. 


Removes an element at a specific index. 


Sets or gets the element at the specified index. 
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class CStringList : public CObject 


The CStringList class supports lists of CString ob- 
jects. All comparisons are done “by value’, meaning 
that the characters in the string are compared instead 
of the addresses of the strings. 


CObject 


z OTTO 


COTATI 


The member functions of CStringList are similar to the member functions of 
class CObList Because of this similarity, you can use the CObArray reference 
documentation for member function specifics. Wherever you see a CObject 
pointer as a return value, substitute a CString. Wherever you see a CObject 
pointer as a function parameter, substitute a const pointer to char. 


CObject*& CObList::GetHead() const; 


for example, translates to 


CString& CStringList::GetHead() const; 


and 


POSITION AddHead( CObject* <newElement> ); 


translates to 


POSITION AddHead( const char* <newElement> ); 


CStringList incorporates the IMPLEMENT_SERIAL macro to support seriali- 
zation and dumping of its elements. If a list of CStrings is stored to an archive, 
either with the overloaded insertion operator or with the Serialize member func- 
tion, each CString element is, in turn, serialized. 


If you need a dump of individual CString elements, you must set the depth of the 
dump context to | or greater. 


When a CStringList object is deleted, or when its elements are removed, the 
CString objects are deleted as appropriate. 


#include <afxcoll.h> 
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Public Members 


Construction/Destruction 
CStringList 
~CStringList 


Head/Tail Access 
GetHead 


GetTail 


Operations 
RemoveHead 
RemoveTail 
AddHead 


AddTail 


RemoveAll 


lteration 
GetHeadPosition 
GetTailPosition 
GetNext 
GetPrev 


Retrieval/Modification 
GetAt 
SetAt 


RemoveAt 


Constructs an empty list for CString objects. 


Destroys a CStringList object. 


Returns the head element of the list (cannot be 
empty). 

Returns the tail element of the list (cannot be 
empty). 


Removes the element from the head of the list. 
Removes the element from the tail of the list. 


Adds an element (or all the elements in another 
list) to the head of the list (makes a new head). 


Adds an element (or all the elements in another 
list) to the tail of the list (makes a new tail). 


Removes all the elements from this list. 


Returns the position of the head element of the list. 
Returns the position of the tail element of the list. 
Gets the next element for iterating. 


Gets the previous element for iterating. 


Gets the element at a given position. 
Sets the element at a given position. 


Removes an element from this list as specified by 
position. 


Insertion 
InsertBefore 
InsertAfter 


Searching 
Find 


FindIndex 
Status 


GetCount 
IsEmpty 
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Inserts a new element before a given position. 


Inserts a new element after a given position. 


Gets the position of an element specified by string 
value. 


Gets the position of an element specified by a zero- 
based index. 


Returns the number of elements in this list. 


Tests for the empty list condition (no elements). 
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class CTime 


A CTime object represents an absolute time and date. The CTime class incor- 
porates the ANSI time_t data type and its associated run-time functions, including 
the ability to convert to and from a Gregorian date and 24-hour time. 


CTime values are based on universal coordinated time (UCT), which is equivalent 
to Greenwich mean time (GMT). The local time zone is controlled by the TZ en- 
vironment variable. 


See the Run-Time Library Reference for more information on the time_t data type 
and the run-time functions that are used by CTime. 


A companion class, CTimeSpan, represents a time interval—the difference 
between two CTime objects. 


#include <afx.h> 
See Also Run-time functions: asctime, _ ftime, gmtime, localtime, strftime, time 
Derivation The CTime and CTimeSpan classes are not designed for derivation. Because 


there are no virtual functions, the size of CTime and CTimeSpan objects is ex- 
actly 4 bytes. Most member functions are inline. 


Public Members 


Construction/Destruction 
CTime Constructs CTime objects in various ways. 


GetCurrentTime Creates a CTime object that represents the current 
time (static member function). 


Extraction 

GetTime Returns a time_t that corresponds to this CTime 
object. 

GetYear Returns the year that this CTime object represents. 

GetMonth Returns the month that this CTime object repre- 
sents (1 through 12). 

GetDay Returns the day that this CTime object represents 


(1 through 31). 


GetHour 
GetMinute 
GetSecond 


GetDayOfWeek 


Conversion 
GetGmtTm 


GetLocalTm 
Format 


FormatGmt 


Operators 
operator = 


operator +, — 


operator +=, —= 


operator ==, <, etc. 


Archive/Dump 


operator << 


operator >> 


CTime 607 


Returns the hour that this CTime object represents 
(O through 23). 


Returns the minute that this CTime object repre- 
sents (0 through 59). 


Returns the second that this CTime object repre- 
sents (O through 59). 


Returns the day of the week (1 for Sunday, 2 for 
Monday, and so forth). 


Breaks down a CTime object into components— 
based on UCT. 


Breaks down a CTime object into components— 
based on the local time zone. 


Converts a CTime object into a formatted string— 
based on the local time zone. 


Converts a CTime object into a formatted string— 
based on UCT. 


Assigns new time values. 


Adds and subtracts CTimeSpan and CTime 
objects. 


Adds and subtracts a CTimeSpan object to and 
from this CTime object. 


Compare two absolute times. 


Outputs a CTime object to CArchive or 
CDumpContext. 


Inputs a CTime object from CArchive. 
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Member Functions 


Syntax 


Parameters 


Remarks 


CTime::CTime 

CTime(); 

CTime( const CTime& timeSrc ); 
CTime( time_t time ); 


CTime( int nYear, int nMonth, int nDay, int nHour, int nMin, int nSec ); 


timeSrc 

Indicates a CTime object that already exists. 
time 

Indicates a time value. 


nYear, nMonth, nDay, nHour, nMin, nSec 
Indicate year, month, day, hour, minute, and second. 


All these constructors create a new CTime object initialized with the specified ab- 
solute time, based on the current time zone. 


Each constructor is described below: 


CTime(); 
Constructs a CTime object with a zero (illegal) value. 


Note Zero is an invalid time. This constructor is provided to allow the defini- 
tion of CTime object arrays. You should initialize such arrays with valid times 
prior to use. 


CTime( const CTime& ); 
Constructs a CTime object from another CTime value. 
CTime( time_t ); 
Constructs a CTime object from a time_t type. 
CTime( int, int, etc.); 
Constructs a CTime object from local time components with each component 
constrained to the following ranges: 


Example 


Syntax 


Parameters 


Remarks 


Return Value 
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Component Range 
nYear 1900-2036 
nMonth 1-12 
nDay 1-31 
nHour 0-23 
nMin 0-59 

nSec 0-59 


This constructor makes the appropriate conversion to UCT. 


The Debug version of the Microsoft Foundation Class Library asserts if one or 
more of the time-day components is out of range. It is your responsibility to 
validate the arguments prior to calling. 


time_t osBinaryTime; // C run-time time (defined in <time.h>) 

time( &osBinaryTime ) ; // get the current time from the operating 
// system 

CTime timel; // empty CTime (@ is illegal time value) 

CTime time2 = timel; // copy constructor 

CTime time3( osBinaryTime ) ; // CTime from C run-time time 

CTime time4( 1999, 3, 19, 22, 15, @ ) ; // 10:15PM March 19, 1999 


CTime::Format 


CString Format( const char* pFormat ); 
pFormat 
Specifies a formatting string similar to the printf formatting string. See the run- 


time function strftime for details. 


Generates a formatted string that corresponds to this CTime object. The time 
value is converted to local time. 


A CString that contains the formatted time. 
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Example 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 
Example 


See Also 


Syntax 
Remarks 


Example 


CTime t( 1999, 3, 19, 22, 15, @ ); // 10:15PM March 19, 1999 
CString s = t.Format( "%A, %“B %d, 4Y" ); 
ASSERT( s == "Tuesday, March 19, 1999" ); 


CTime::FormatGmt 


CTime::FormatGmt 


CString FormatGmt( const char* pFormat ); 
pFormat 
A formatting string similar to the printf formatting string. See the run-time 


function strftime for details. 


Generates a formatted string that corresponds to this CTime object. The time 
value is not converted and thus reflects UCT. 


A CString that contains the formatted time. 
See the example for Format. 


CTime::Format 


CTime::GetCurrentTime 
static CTime GetCurrentTime(); 
Returns a CTime object that represents the current time. 


CTime t = CTime::GetCurrentTime(); 
ASSERT( ( t.GetYear() >= 1999 ) && ( t.GetYear() <= 2000 ) ); 


Syntax 
Remarks 


Example 


See Also 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 
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CTime::GetDay 


int GetDay() const; 
Returns the day of the month, based on local time, in the range | through 31. 


CTime t( 1999, 3, 19, 22, 15, @ ); // 10:15PM March 19, 1999 
ASSERT( t.GetDay() == 19 ); 

ASSERT( t.GetMonth() == 3 ); 

ASSERT( t.GetYear() == 1999 ); 


CTime::GetDayOfWeek 


CTime::GetDayOfWeek 


int GetDayOfWeek() const; 


Returns the day of the week based on local time. 1 = Sunday, 2 = Monday, ... 
7 = Saturday. 


CTime::GetGmtTm 


struct tm* GetGmtTm( struct tm* ptm = NULL ) const; 


ptm 
Points to a buffer that will receive the time data. If this pointer is NULL, an in- 
ternal, statically allocated buffer is used. The data in this default buffer is over- 
written as a result of calls to other CTime member functions. 


Gets a struct tm that contains a decomposition of the time contained in this 
CTime object. GetGmtTm returns UCT. 
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Return Value 


Example 


Syntax 


Parameters 


Remarks 


Return Value 


A pointer to a filled-in struct tm as defined in the include file TIME.H. The mem- 
bers are as follows: 


Field Value Stored 

tm_sec Seconds 

tm_min Minutes 

tm_hour Hours (0-23) 

tm_mday Day of month (1-31) 

tm_mon Month (Q—11; January = 0) 
tm_year Year (actual year minus 1900) 
tm_wday Day of week (1—7; Sunday = 1) 
tm_yday Day of year (O—365; January 1 = 0) 
tm_isdst Always 0 


Note The year in struct tm is in the range —1 to 136; the year in the CTime inter- 
face is in the range 1900 to 2036 (inclusive). 


See the example for GetLocalTm. 


CTime::GetLocallm 


struct tm* GetLocalTm( struct tm* ptm ) const; 


ptm 
Points to a buffer that will receive the time data. If this pointer is NULL, an in- 
ternal, statically allocated buffer is used. The data in this default buffer 1s over- 
written as a result of calls to other CTime member functions. 


Gets a struct tm containing a decomposition of the time contained in this CTime 
object. GetLocalTm returns local time. 


A pointer to a filled-in struct tm as defined in the include file TIME.H. See 
GetGmtTm for the structure layout. 
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Example CTime t( 1999, 3, 19, 22, 15, @ ); // 10:15PM March 19, 1999 
struct tm* osTime; // a pointer to a structure containing time elements 
osTime = t.GetLocalTm( NULL ); 
ASSERT( osTime->tm_mon == 2 ); // note zero-based month! 


CTime::GetHour 


Syntax int GetHour() const; 

Remarks Returns the hour, based on local time, in the range 0 through 23. 

Example CTime t( 1999, 3, 19, 22, 15, @ ); // 10:15PM March 19, 1999 
) 


ASSERT( t.GetSecond() == @ 
ASSERT( t.GetMinute() == 1 
ASSERT( t.GetHour() == 22 


+] 


CTime::GetMinute 


syntax int GetMinute() const; 
Remarks Returns the minute, based on local time, in the range 0 through 59. 
Example See the example for GetHour. 


CTime::GetMonth 


Syntax int GetMonth@Q const; 
Remarks Returns the month, based on local time, in the range 1 through 12 (1 = January). 


Example See the example for GetDay. 
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Syntax 
Remarks 


Example 


Syntax 
Remarks 


Example 


See Also 


syntax 
Remarks 


Example 


CTime::GetSecond 


CTime::GetSecond 


int GetSecond() const; 
Returns the second, based on local time, in the range 0 through 59. 


See the example for GetHour. 


CTime::GetTime 


time_t GetTime() const; 
Returns a time_t value for the given CTime object. 


CTime t( 1999, 3, 19, 22, 15, @ ); // 10:15PM March 19, 1999 
time_t osBinaryTime = t.GetTime(); // time_t defined in <time.h> 
printf( "time_t = 41d\\n", osBinaryTime ); 


CTime constructors 


CTime::GetYear 


int GetYear(); 
Returns the year, based on local time, in the range 1900 to 2036. 


See the example for GetDay. 


Operators 


Syntax 


Remarks 


Example 


See Also 


Syntax 


Remarks 


CTime::operator +, - 615 


CTime::operator = 


const CTime& operator =( const CTime& timeSrc ); 


const CTime& operator =( time_t t ); 


These overloaded assignment operators copy the source time into this CTime 
object. 


The internal time storage in a CTime object is independent of time zone. Time- 
zone conversion is not necessary during assignment. 


time_t osBinaryTime; // C run-time time (defined in <time.h>) 


CTime tl = osBinaryTime; // assignment from time_t 
CTime t2 = tl; // assignment from CTime 
CTime constructors 


CTime::operator +, — 


CTime operator +( CTimeSpan timeSpan ) const; 
CTime operator — ( CTimeSpan timeSpan ) const; 


CTimeSpan operator — ( CTime time ) const; 


CTime objects represent absolute time. CTimeSpan objects represent relative 
time. The first two operators allow you to add and subtract CTimeSpan objects to 
and from CTime objects. The third allows you to subtract one CTime object from 
another to yield a CTimeSpan object. 


616 


Example 


Syntax 


Remarks 


Example 


syntax 


Remarks 


CTime::operators +=, -= 


CTime t1( 1999, 3, 19, 22, 15, @ ); // 10:15PM March 19, 1999 
CTime t2( 1999, 3, 20, 22, 15, @ ); // 10:15PM March 20, 1999 
CTimeSpan ts = t2 - tl; // subtract 2 CTimes 

ASSERT( ts.GetTotalSeconds() == 86400L ); 

ASSERT( ( t1 + ts ) == t2 ); // add a CTimeSpan to a CTime 
ASSERT( ( t2 - ts ) == tl ); // subtract a CTimeSpan from a CTime 


CTime::operator +=, -= 


const CTime& operator +=( CTimeSpan timeSpan ); 


const CTime& operator —=( CTimeSpan timeSpan ); 


These operators allow you to add and subtract a CTimeSpan object to and from 
this CTime object. 


CTime tC 1999; 35°19 223 1sy. Ode fF VOC OPM March: 195, 1999 
t += CTimeSpan( @, 1, @, @ ); // one hour exactly 
ASSERT( t.GetHour() == 23 ); 


CTime Comparison Operators 


BOOL operator ==( CTime time ) const; 
BOOL operator !=( CTime time ) const; 
BOOL operator <( CTime time ) const; 
BOOL operator >( CTime time ) const; 
BOOL operator <=( CTime time ) const; 


BOOL operator >=( CTime time ) const; 


These operators compare two absolute times and return TRUE if the condition is 
true; otherwise FALSE. 


Example 


Syntax 


Remarks 


Example 


See Also 
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CTime tl CTime::GetCurrentTime(); 

CTime t2 = tl + CTimeSpan( @, 1, 0, @ ); // 1 hour later 
ASSERT( tl != t2 ); 

ASSERT( t1 < t2 ); 

ASSERT( t1 <= t2 ); 


CTime::operators <<, >> 


friend CDumpContext& operator <<( CDumpContext& dc, CTime time ); 
friend CArchive& operator <<( CArchive& ar, CTime time ); 


friend CArchive& operator >>( CArchive& ar, CTime& rtime ); 


The CTime insert (<<) operator supports diagnostic dumping and storing to an ar- 
chive. The extract (>>) operator supports loading from an archive. 


When you send a CTime object to the dump context, the local time is displayed in 
readable date-time format. 


CTime t( 1999, 3, 19, 22, 15, @ ); // 10:15PM March 19, 1999 
afxDump << t << "\\n"; // prints 'CTime("Tue Mar 19 22:15:00 1999")' 


extern CArchive ar; 
if( ar.IsLoading() ) 
ar >> t; 
else 
ar << t; 


CArchive, CDumpContext 
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class CTimeSpan 


A CTimeSpan object represents a relative time span. The CTimeSpan class incor- 
porates the ANSI time_t data type and its associated run-time functions. These 
functions convert seconds to various combinations of days, hours, minutes, and 
seconds. 


A CTimeSpan object keeps time in seconds. Because the CTimeSpan object is 
stored as a signed number in 4 bytes, the maximum allowed span is + 68 years, 
approximately. 


A companion class, CTime, represents an absolute time. A CTimeSpan ts the 
difference between two CTimes. 


#include <afx.h> 
See Also Run-time functions: asctime, _ftime, gmtime, localtime, strftime, time 
Derivation The CTime and CTimeSpan classes are not designed for derivation. Because 


there are no virtual functions, the size of both CTime and CTimeSpan objects is 
exactly 4 bytes. Most member functions are inline. 


— Public Members 


Construction/Destruction 


CTimeSpan Constructs CTimeSpan objects in various ways. 

Extraction 

GetDays Returns the number of complete days in this 
CTimeSpan. 

GetHours Returns the number of hours in the current day 
(—23 through 23). 

GetTotalHours Returns the total number of complete hours in this 
CTimeSpan. 

GetMinutes Returns the number of minutes in the current hour 


(—59 through 59). 


GetTotalMinutes 
GetSeconds 


GetTotalSeconds 


Conversion 
Format 


Operators 
operator = 
operator +, — 


operator +=, —= 


operator ==, <, etc. 


Archive/Dump 


operator << 


operator >> 


CTimeSpan 


Returns the total number of complete minutes in 
this CTimeSpan. 


Returns the number of seconds in the current 
minute (—59 through 59). 


Returns the total number of complete seconds in 
this CTimeSpan. 


Converts a CTimeSpan into a formatted string. 


Assigns new time-span values. 
Adds and subtracts CTimeSpan objects. 


Adds and subtracts a CTimeSpan object to and 
from this CTimeSpan. 


Compare two relative time values. 


Outputs a CTimeSpan object to CArchive or 
CDumpContext. 


Inputs a CTimeSpan object from CArchive. 
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Member Functions 


Syntax 


Parameters 


Remarks 


CTimeSpan::CTimeSpan 


CTimeSpanQ); 
CTimeSpan( const CTimeSpan& timeSpanSrc ); 
CTimeSpan( time_t time ); 


CTimeSpan( LONG [Days, int nHours, int nMins, int nSecs ); 


timeSpanSrc 

Indicates a CTimeSpan object that already exists. 
time 

Indicates a time_t time value. 


[Days, nHours, nMins, nSecs 
Indicate days, hours, minutes, and seconds. 


All these constructors create a new CTimeSpan object initialized with the 
specified relative time. Each constructor is described below: 


CTimeSpan(); 
Constructs an uninitialized CTimeSpan object. 
CTimeSpan( const CTimeSpan& ); 
Constructs a CTimeSpan object from another CTimeSpan value. 
CTimeSpan( time_t ); 
Constructs a CTimeSpan object from a time_t type. This value should be the 
difference between two absolute time_t values. 
CTimeSpan( LONG, int, int, int ); 
Constructs a CTimeSpan object from components with each component con- 
strained to the following ranges: 


Component Range 

[Days O0—25,000 (approximately) 
nHours 0-23 

nMins 0-59 


nSecs 0-59 
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Note The Debug version of the Microsoft Foundation Class Library asserts if 
one or more of the time-day components is out of range. It is your responsi- 
bility to validate the arguments prior to calling. 


Example CTimeSpan tsl; // Uninitialized time value 
CTimeSpan ts2a( tsl ); // Copy constructor 
CTimeSpan ts2b = tsl; // Copy constructor again 
CTimeSpan ts3( 100 ); // 10@ seconds 
CTimeSpan ts4( @, 1, 5, 12 ); // 1 hour, 5 minutes, and 12 seconds 


CTimeSpan::Format 


Syntax CString Format( const char* pFormat ); 


Parameters pFormat 
Indicates a formatting string similar to the printf formatting string. Formatting 
codes, preceded by a percent (%) sign, are replaced by the corresponding 
CTimeSpan component. Other characters in the formatting string are copied 
unchanged to the returned string. 


The formatting codes for Format are listed below: 


Value Meaning 
%D Total days in this CTimeSpan 
%H Hours in the current day 
%M Minutes in the current hour 
%S Seconds in the current minute 
% %o Percent sign 
Remarks Generates a formatted string that corresponds to this CTimeSpan. 


The Debug version of the library checks the formatting codes and asserts if the 
code is not in the table above. 
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Return Value A CString object that contains the formatted time. 

Example CTimeSpan ts( 3, 1, 5, 12 ); // 3 days, 1 hour, 5 min, and 12 sec 
CString s = ts.Format( "Total days: %4D, hours: 4H, min: %4M, sec: 4S" ); 
ASSERT( s == "Total days: 3, hours: @1, min: 05, sec: 12" ); 


CTimeSpan::GetDays 
syntax LONG GetDays() const; 


Remarks Returns the number of complete days. This value may be negative if the time span 
is negative. 


Example CTimeSpan ts( 3, 1, 5, 12 ); // 3 days, 1 hour, 5 min, and 12 sec 
ASSERT( ts.GetDays() == 3 ); 


CTimeSpan::GetHours 


syntax int GetHours() const; 
Remarks Returns the number of hours in the current day. The range is —23 through 23. 
Example CTimeSpan ts( 3, 1, 5, 12 ); // 3 days, 1 hour, 5 min, and 12 sec 


ASSERT( ts.GetHours() == 1 
ASSERT( ts.GetMinutes() == 
ASSERT( ts.GetSeconds() == 


ve 
a. 
1 ae 
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CTimeSpan::GetMinutes 


Syntax int GetMinutes() const; 
Remarks Returns the number of minutes in the current hour. The range is —59 through 59. 
Example See the example for GetHours. 


CTimeSpan::GetSeconds 


Syntax int GetSeconds() const; 
Remarks Returns the number of seconds in the current minute. The range is —59 through 59. 
Example See the example for GetHours. 


CTimeSpan::GetTotalHours 


Syntax LONG GetTotalHours() const; 
Remarks Returns the total number of complete hours in this CTimeSpan. 
Example CTimeSpan ts( 3, 1, 5, 12 ); // 3 days, 1 hour, 5 min, and 12 sec 


ASSERT( ts.GetTotalHours() == 73 ); 
ASSERT( ts.GetTotalMinutes() == 4385 ); 
ASSERT( ts.GetTotalSeconds() == 263112 ); 
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CTimeSpan::GetTotalMinutes 


Syntax LONG GetTotalMinutes() const; 
Remarks Returns the total number of complete minutes in this CTimeSpan. 
Example See the example for GetTotalHours. 


CTimeSpan::GetTotalSeconds 


syntax LONG GetTotalSeconds() const; 
Remarks Returns the total number of complete seconds in this CTimeSpan. 


Example See the example for GetTotalHours. 


Operators 


Syntax 


Remarks 


Example 


See Also 


Syntax 


Remarks 


Example 
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CTimeSpan::operator = 


const CTimeSpan& operator =( const CTimeSpan& timeSpanSrc ); 


The overloaded assignment operator copies the source CTimeSpan timeSpanSrc 
object into this CTimeSpan object. 


CTimeSpan tsl; 

CTimeSpan ts2( 3, 1, 5, 12 ); // 3 days, 1 hour, 5 min, and 12 sec 
TSl=. ts2% 

ASSERT( tsl == ts2 ); 


CTimeSpan constructors 


CTimeSpan::operator +, — 


CTimeSpan operator —( CTimeSpan timeSpan ) const; 


CTimeSpan operator +( CTimeSpan timeSpan ) const; 


These two operators allow you to add and subtract CTimeSpans to and from each 
other. 


CTimeSpan tsl( 3, 1, 5, 12 ); // 3 days, 1 hour, 5 min, and 12 sec 
CTimeSpan ts2( 10@ ); // 100 seconds 

CTimeSpan ts3 = tsl + ts2; 

ASSERT( ts3.GetSeconds() == 52 ); // 6 min, 52 sec 
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Syntax 


Remarks 


Example 


Syntax 


Remarks 


Example 


CTimeSpan::operator +=, —= 


CTimeSpan::operator +=, -= 


const CTimeSpan& operator +=( CTimeSpan timeSpan ); 


const CTimeSpan& operator —=( CTimeSpan timeSpan ); 


These operators allow you to add and subtract a CTimeSpan to and from this 
CTimeSpan. 


CTimeSpan tsl1( 10 ); // 10 seconds 
CTimeSpan ts2( 100 ); // 100 seconds 
Us? ==. Ts i+ 

ASSERT( ts2.GetTotalSeconds() == 9@ ); 


CTimeSpan Comparison Operators 


BOOL operator ==( CTimeSpan timeSpan ) const; 
BOOL operator !=( CTimeSpan timeSpan ) const; 
BOOL operator <( CTimeSpan timeSpan ) const; 
BOOL operator >( CTimeSpan timeSpan ) const; 
BOOL operator <=( CTimeSpan timeSpan ) const; 


BOOL operator >=( CTimeSpan timeSpan ) const; 


These operators compare two relative time values. They return TRUE if the condi- 
tion is true; otherwise FALSE. 


CTimeSpan tsl( 100 ); 
CTimeSpan ts2( 110 ); 
ASSERT( ( tsl != ts2 ) && ( tsl < ts2 ) && ( tsl <= ts2 ) ); 
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Syntax 


Remarks 


Example 


CTimeSpan::operators <<, >> 


friend CDumpContext& operator <<( CDumpContext& dc, 
CTimeSpan timeSpan ); 


friend CArchive& operator <<( CArchive& ar, CTimeSpan timeSpan ); 


friend CArchive& operator >>( CArchive& ar, CTimeSpan& rtimeSpan ); 


The CTimeSpan insert (<< ) operator supports diagnostic dumping and storing to 
an archive. The extract (>>) operator supports loading from an archive. 


When you send a CTimeSpan object to the dump context, the value is displayed 
in a human-readable format that shows days, hours, minutes, and seconds. 


CTimeSpan ts( 3, 1, 5, 12 ); // 3 days, 1 hour, 5 min, and 12 sec 
ifdef _ DEBUG 

afxDump << ts << "\\n"; 

dtendi f 

// prints 'CTimeSpan(3 days, 1 hours, 5 minutes and 12 seconds)' 


extern CArchive ar; 
if( ar.IsLoading( )) 
ar >> ts; 
else 
ar << ts; 
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CWinApp 


class CWinApp : public CObject 


Use the CWinApp class to create a Windows appli- 
cation object. An application object provides member 
functions for initializing the application (and each in- 
stance of it) and for running the application. 


CWinApp | 


Each application that uses the Foundation classes can only contain one CWinApp 
object. This object is constructed when other C++ global objects are constructed 
and is already available when Windows calls the WinMain function, which is sup- 
plied by the Foundation class library. Declare your CWinApp object at the global 
level or statically. 


Typically, you will derive an application class from CWinApp and override the 
InitInstance member function to create your application’s main window object. 


The Microsoft Foundation Class Library provides a number of global functions 
that you can use to access your CWinApp object, as shown by the following list. 
These functions are available from C or C++. 


Function Purpose 

AfxGetApp Obtain a pointer to the CWinApp object. 

AfxGetInstanceHandle Obtain a handle to the current application 
instance. 


AfxGetResourceHandle Obtain a handle to the application’s resources. 


AfxGetAppName Obtain a pointer to a string containing the 
application’s name. 


Note Most users of the Foundation classes will use the default WinMain provided 
by the Foundation class library. If you provide your own version of WinMain, 
you must call AfxWinInit before using a Foundation class to attach your 
CWinApp object to the Microsoft Foundation Class Library. 


Public Members 


Data Members 
m_pszAppName 


m_hInstance 
m_hPrevInstance 
m_lIpCmdLine 
m_nCmdShow 


m_pMainWnd 


Construction/Destruction 
CWinApp 


Operations 
LoadCursor 


LoadStandard Cursor 
LoadOEMCursor 
LoadIcon 
LoadStandardIcon 


LoadOEM Icon 
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Specifies the name of the application. 


Corresponds to the h/Instance parameter passed by 
Windows to WinMain. 


Corresponds to the hPrev/nstance parameter 
passed by Windows to WinMain. 


Corresponds to the [pCmdLine parameter passed 
by Windows to WinMain. 


Corresponds to the nCmdShow parameter passed 
by Windows to WinMain. 


Holds a pointer to the application’s main window. 
See InitInstance for an example of how to initial- 
ize m_pMainWnd. 


Constructs a CWinApp object. 


Loads a cursor resource, or a resource handle if the 
resource has been loaded previously. 


Loads a Windows predefined cursor specified by 
IDC_ constants from WINDOWS.H. 


Loads a Windows OEM predefined cursor speci- 
fied by OCR_ constants from WINDOWS.H. 


Loads an icon resource, or a resource handle if the 
resource has been loaded previously. 


Loads a Windows predefined icon specified by 
IDI constants from WINDOWS.H. 


Loads a Windows OEM predefined icon specified 
by OIC_ constants from WINDOWS.H. 
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Overridables 
InitA pplication 


InitInstance 


Run 
Onldle 
ExitInstance 


PreTranslateMessage 


Protected Members 


m_msgCur 


Performs any application-level initialization when 
overridden. (Sometimes override. ) 


Performs Windows instance initialization, such as 
creating your window objects when overridden. 
(Always override.) 


Runs the default message loop. Override to cus- 
tomize the message loop. (Seldom override.) 


Overrride to perform application-specific idle-time 
processing. (Sometimes override.) 


Override to clean up when your application termi- 
nates. (Sometimes override.) 


Filters messages before they are dispatched to the 
Windows functions TranslateMessage and 
DispatchMessage. (Seldom override.) 


Specifies the last window message retrieved by 
Run; only useful if the message is currently being 
processed. 


CWinApp::InitApplication 631 


Member Functions 


Syntax 


Parameters 


Remarks 


Syntax 


Remarks 


Return Value 


Syntax 


Remarks 


CWinApp::CWinApp 
CWinApp( const char* pszAppName = NULL ); 


pszAppName 
A null-terminated string containing the Windows application name for your 
application. If this argument is not supplied or is NULL, CWinApp uses the 
filename of the executable file by default. 


Constructs a CWinApp object and passes pszAppName to be stored as the 
application name. This constructor is invoked by your global application object 
definition. You can have only one CWinApp object in your application. The con- 
structor stores a pointer to the CWinApp object in a Microsoft Foundation- 
defined global variable. This is so the WinMain can call the object’s member 
functions to initialize and run the application. 


CWinApp::Exitinstance 


virtual int ExitInstance(Q); 


Override this function to clean up when your application terminates. 


ExitInstance is called by the default Run member function. 


The application’s exit code, where 0 indicates no errors and values greater than 0 
indicate an error. This value is used as the return value from WinMain. 


CWinApp::InitApplication 
virtual BOOL InitApplicationQ; 


Windows allows several copies of the same program to be running at the same 
time. Thus, application initialization is conceptually divided into two sections: one- 
time application initialization that is done the first time the program runs and 
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Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


InitInstance 


instance initialization that runs each time a copy of the program runs, including the 
first time. This function is called by the Foundation library version of WinMain. 
Override InitApplication if your application needs one-time initialization such as 
Windows class registration. 


TRUE if initialization is successful; otherwise FALSE. 


CWinApp::InitInstance 


CWinApp::Initinstance 


virtual BOOL InitInstance(); 


Windows allows several copies of the same program to be running at the same 
time. Thus, application initialization is conceptually divided into two sections: one- 
time application initialization that is done the first time the program runs and in- 
stance initialization that runs each time a copy of the program runs, including the 
first time. This function is called by the Foundation library implementation of 
WinMain. Override InitInstance to provide initialization for each new instance 

of your application running under Windows. Typically, you override InitInstance 
to construct your main window object and set m_ pMainWnd to point to that win- 
dow, as shown here. 


BOOL CDerivedApp::InitInstance( ) 


{ 
m_pMainWnd = new CDerivedWindow(); 
m_pMainWnd->ShowWindow( m_nCmdShow ); 
m_pMainWnd->UpdateWindow( ); 
return TRUE; 

} 


TRUE if initialization is successful; otherwise FALSE. 


CWinApp::InitA pplication 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


CWinApp::Loadicon 633 


CWinApp::LoadCursor 


HCURSOR LoadCursor( LPSTR [pCursorName ); 
HCURSOR LoadCursor( UINT n/DCursor ); 


[pCursorName 
Points to a null-terminated string that contains the name of the cursor resource. 
You can use a CString in place of an LPSTR. 


nlDCursor 
ID number of the resource. 


Loads the cursor resource named by [pCursorName or specified by nJDCursor 
from the current executable file. LoadCursor loads the cursor into memory only 
if it has not been previously loaded. 


Use the LoadStandardCursor or LoadOQEMCursor member functions to access 
the predefined Windows cursors. 


A handle to a cursor resource. If unsuccessful, returns NULL. 


CWinApp::LoadStandardCursor, CWinApp::LoadOEMCursor, 
::LoadCursor 


CWinApp::Loadicon 


HICON LoadIcon( LPSTR Ip/conName ); 
HICON LoadIcon( UINT n/DIcon ); 


[pIconName 
Points to a null-terminated string that contains the name of the icon resource. 
You can also use a CString for this argument. 


nlDIcon 
ID number of the resource. 


Loads the icon resource named by /pIconName or specified by nIDIcon from the 
executable file. LoadIcon loads the icon only if it has not been previously loaded. 
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Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


You can use the LoadStandardIcon or LoadOEMIcon member functions to | 
access the predefined Windows icons. 


A handle to an icon resource. If unsuccessful, returns NULL. 


CWinApp::LoadStandardIcon, CWinApp::LoadOEMIcon, ::LoadIcon 


CWinApp::LoadOEMCursor 


HCURSOR LoadOEMCursor( UINT n/DCursor ); 


nIDCursor 
An OCR_ manifest constant identifier that specifies a predefined Windows cur- 
sor. You must have #define OQEMRESOURCE in your source file to get 
access to the OCR_ constants in WINDOWS.H. 


Loads the Windows predefined cursor resource specified by nJDCursor. 


Use LoadOEMCursor or the LoadStandardCursor member function to access 
the predefined Windows cursors. 


A handle to a cursor resource. If unsuccessful, returns NULL. 


CWinApp::LoadCursor, CWinApp::LoadStandardCursor, ::LoadCursor 


CWinApp::LoadOEMIcon 


HICON LoadOEMIcon( UINT n/DIcon ); 


nlDIcon 
An OIC_ manifest constant identifier that specifies a predefined Windows 
icon. You must have #define OEMRESOURCE in your source file to get 
access to the OIC_ constants in WINDOWS.H. 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 
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Loads the Windows predefined icon resource specified by n/DIcon. 


Use LoadOEM Icon or the LoadStandardIcon member function to access the 
predefined Windows icons. 


A handle to an icon resource. If unsuccessful, returns NULL. 


CWinApp::LoadStandardIcon, CWinApp::LoadIcon, ::LoadIcon 


CWinApp::LoadStandardCursor 


HCURSOR LoadStandardCursor( LPSTR /[pCursorName ); 


lpCursorName 


An IDC_ manifest constant identifier that specifies a predefined Windows cur- 
sor. These identifiers are defined in WINDOWS.H. The following list shows 
the possible predefined values for /pCursorName: 


Value Meaning 

IDC_ARROW Standard arrow cursor 

IDC_IBEAM Standard text-insertion cursor 

IDC_ WAIT Hourglass cursor used when Windows performs a 
time-consuming task 

IDC_CROSS Cross-hair cursor for selection 

IDC_UPARROW Arrow pointing straight up 

IDC_SIZE Cursor to use when resizing a window 

IDC_ICON Cursor to use when dragging a file 


IDC_SIZENWSE 


IDC_SIZENESW 


IDC_SIZEWE 
IDC_SIZENS 


Two-headed arrow with ends at upper left and lower 
right 

Two-headed arrow with ends at upper right and 
lower left 


Horizontal two-header arrow 


Vertical two-headed arrow 
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Remarks Loads the Windows predefined cursor resource specified by [pCursorName. 


Use LoadStandardCursor or the LoadQEMCursor member function to access 
the predefined Windows cursors. 


Return Value A handle to a cursor resource. If unsuccessful, returns NULL. 


See Also CWinApp::LoadOEMCursor, CWinApp::LoadCursor, ::LoadCursor 


CWinApp::LoadStandardlicon 


Syntax HICON LoadStandardIcon( LPSTR IpIconName ); 


Parameters lpIconName 
A manifest constant identifier that specifies a predefined Windows icon. These 
identifiers are defined in WINDOWS.H. The following list shows the possible 
predefined values for [pIconName: 


Value Meaning 

IDI_APPLICATION Default application icon 

IDI_HAND Hand-shaped icon used in serious warning 
messages 

IDI_QUESTION Question mark shape used in prompting 
messages 

IDL EXCLAMATION Exclamation point shape used in warning 
messages 

IDL ASTERISK Asterisk shape used in informative messages 

Remarks Loads the Windows predefined icon resource specified by lpIconName. 


Use LoadStandardIcon or the LoadQEMIcon member function to access the 
predefined icons used by Windows. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 
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A handle to an icon resource (a bitmap defining the icon). If unsuccessful, returns 
NULL. 


CWinApp::LoadOEMIcon, CWinApp::LoadIcon, ::LoadIcon 


CWinApp::Onldle 


virtual BOOL Onldle( LONG /Count ); 


[Count 
A counter incremented each time GetMessage finds the message queue empty. 
This count is reset to 0 each time a new message is processed. /Count can be 
used to determine relatively how long the application has been idling without 
processing a message. 


Override this member function to perform idle-time processing. Onldle is called 
when the application’s message queue is empty. Use your override to call your 
own idle-handler members for such tasks as background recalculation in a spread- 
sheet, background repagination in a word processor, file backup, and the like. 


The /Count parameter is incremented each time GetMessage finds the queue 
empty and reset to 0 each time a new message is processed. You can call your 
different idle routines based on this count. 


Do not perform lengthy tasks during OnIdle because your application cannot 
process user input until OnIdle returns. 


Note The default implementation of OnIdle performs internal data structure 
cleanup. Therefore, if you override OnIdle, you must explicitly call 
CWinApp::Onldle in your overridden version to get the default processing. 


TRUE to receive more idle processing time; FALSE if no more idle time 1s 
needed. 
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Syntax 


Parameters 


Remarks 


Return Value 


Syntax 


Remarks 


Return Value 


CWinApp::PreTranslateMessage 
virtual BOOL PreTranslateMessage( MSG* pMseg ); 


pMsg 
A pointer to a MSG structure containing the message to process. 


Override this function to filter window messages before they are dispatched to 
the Windows functions TranslateMessage and DispatchMessage. The default 
implementation performs access-key translation, so you must call 
PreTranslateMessage in your overridden version. 


TRUE if the message was fully processed in PreTranslateMessage and should 
not be passed to the Windows functions TranslateMessage and 
DispatchMessage. FALSE if the message should be processed in the normal way. 


CWinApp::Run 


virtual int RunQ; 


Provides a default message loop. Run acquires and dispatches Windows messages 
until a WM_ QUIT message is received. If the application’s message queue cur- 
rently contains no messages, Run calls OnIdle to perform idle-time processing. In- 
coming messages are passed to PreTranslateMessage for special processing, then 
passed to the Windows function TranslateMessage for standard keyboard transla- 
tion, and finally DispatchMessage is called. 


Run is rarely overridden, but you can override it to provide special behavior. 


An int value that is returned by WinMain. 
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Data Members 


CWinApp::m_hinstance 


Remarks Corresponds to the hInstance parameter passed by Windows to WinMain. The 
m_hInstance data member is a handle to the current instance of the application 
running under Windows. This is returned by AfxGetInstanceHandle. 


CWinApp::m_hPrevinstance 


Remarks Corresponds to the hPrevinstance parameter passed by Windows to WinMain. 
The m_hPrevInstance data member has the value NULL if this is the first in- 
stance of the application that is running. 


CWinApp::m_IpCmdLine 


Remarks Corresponds to the IpCmdLine parameter passed by Windows to WinMain. Use 
m_IpCmdLine to access any command-line arguments entered when the applica- 
tion was started. 


CWinApp::m_msgCur 


Remarks Corresponds to the last window message retrieved by Run; only useful if the mes- 
sage 1s currently being processed. 
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Remarks 


Remarks 


Remarks 


CWinApp::m_nCmdShow 


CWinApp::m_nC€mdShow 


Corresponds to the nCmdShow parameter passed by Windows to WinMain. If 
m_nCmdShow is TRUE, the first call to CWnd::ShowWindow makes the main 
window visible. You can pass m_nCmdShow as an argument when you call 
Show Window for your application’s main window. 


CWinApp::m_pMainWnd 


Use this data member to store a pointer to your application’s main window object. 
The Foundation class library will automatically terminate your application when 
the window referred to by m_ pMainWnd is closed. If you don’t store a valid 
CWhnd pointer here, you must explicitly call the Windows function 
PostQuitMessage to terminate your application. 


CWinApp::m_pszAppName 


Specifies the name of the application (optionally provided to the constructor or ex- 
tracted from .EXE name if not provided). 


Returned by AfxGetAppName. 
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class CWindowDC : public CDC 


The CWindowDC class is derived from CDC. It calls 
the Windows functions GetWindowDC at construc- 
tion time and ReleaseDC at destruction time. This 
means that a CWindowDC object accesses the entire 
Screen area of a CWnd—both client and nonclient 
areas. 


Pr geet rere! 


@ 


See Also CDC 
Public Members 
Construction/Destruction 
CWindowDC Constructs a CWindowDC object. 
~CWindowDC Destroys the CWindowDC object. 
Protected Members 
m_hWnd The HWND to which this CWindowDC is 


attached. 
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Member Functions 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 
Remarks 


See Also 


CWindowDC::CWindowDC 


CWindowDC( CWnd* pWid ) 
throw( CResourceException ); 


pWnd 
The window whose client area the device context object will access. 


Constructs a CWindowDC object that accesses the entire screen area (both client 


and nonclient) of the CWnd object pointed to by pWnd. The constructor calls the 
Windows function GetDC. 


An exception (of type CResourceException) is thrown if the Windows GetDC 
call fails. A device context may not be available if Windows has already allocated 
all of its available device contexts. Your application competes for the five com- 
mon display contexts available at any given time under Windows. 


CDC, CClientDC, CWnd 


CWindowDC::~CWindowDC 


virtual ~CWindowDC(); 
Destroys a CWindowDC object and calls the Windows ReleaseDC function. 


CDC, CClientDC, CWnd, ::ReleaseDC 
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Data Members 


CWindowDC::m_hWhnd 


Remarks The HWND of the CWnd pointer used to construct the CWindowDC object. 
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class CWnd : public CObject 


The CWnd class provides the base functionality of 
all window classes in the Microsoft Foundation Class 
Library. 


A CWnd object is actually distinct from a Windows 

window, but the two are tightly linked. A CWnd object is created or destroyed by 
the CWnd constructor and destructor. The Windows window, on the other hand, 
is a data structure internal to Windows that is created by the CreateEx member 
function and destroyed by the CWnd virtual destructor. The Destroy Window 
function, one of the few public virtual CWnd member functions, destroys the 
Windows window without destroying the object. 


The CWnd class and the message-map mechanism hide the WndProc function. 
Incoming Windows notification messages are automatically routed through the 
message map to the proper OnMessage CWnd member functions. You override 
the OnMessage member function to handle that member’s particular message in 
your derived classes. 


The CWnd class also provides the functionality of a Windows child window. 


To create a useful child window for your application, derive a class from CWnd. 
Add member variables to the derived class to store data specific to your applica- 
tion. Implement message-handler member functions and a message map in the 
derived class to specify what happens when messages are directed to the window. 


You create a child window in two steps. First, call the constructor CWnd to con- 
struct the CWnd object, then call the Create member function to create the child 
window and attach it to the CWnd object. 


Construction can be a one-step process in a derived class. Write a constructor for 
the derived class and call Create from within the constructor. 


When the user terminates your child window, destroy the CWnd object, or call the 
DestroyWindow member function to remove the window and destroy its data 
structures. If you allocate any memory in the CWnd object, override the CWnd 
destructor to dispose of the allocations. 
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Within the Microsoft Foundation Class Library, further classes are derived from 
CWnd to provide specific window types. Three of these classes, CFrameWnd, 
CMDIFrameWnd, and CMDIChildWnd, contain further window functionality 
and are designed for further derivation. The control classes derived from CWnd, 
such as CDialog and CButton, can be used directly, or can also be used for 


further derivation of classes. 


See Also 


CDialog, CModalDialog, CStatic, CButton, CEdit, CListBox, CComboBox, 


CScrollBar, CFrameWnd, CMDIFrameWnd, CMDIChildWnd 


Public Members 


Data Members 
m_hWnd 
wndTop 


wndBottom 


Construction/Destruction 
CWnd 
~CWnd 


Destroy Window 


Initialization 
Create 


GetStyle 
Attach 
Detach 


FromHandle 


Indicates the HWND attached to this CWnd. 


Indicates a static CWnd to use with the 
SetWindowPos member function to indicate that 
CWnd should be moved to the top of the window 
list. 


Indicates a static CWnd to use with the 
SetWindowPos member function to indicate that 
CWhnd should be moved to the bottom of the win- 
dow list. 


Constructs a CWnd object. 


Destroys a CWnd object and destroys the attached 
window. 


Destroys the attached Windows window. 


Creates and initializes the child window associated 
with the CWnd object. 


Returns the current window style. 
Attaches a Windows handle to a CWnd object. 


Detaches a Windows handle from a CWnd object 
and returns the handle. 


Returns a pointer to a CWnd object when given a 
handle to a window. If a CWnd object is not 
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DeleteTempMap 


GetSafeHwnd 


Message Functions 
SendMessage 


PostMessage 


Window Text Functions 
SetWindowText 


GetWindowText 
GetWindowTextLength 


SetFont 
GetFont 


CMenu Functions 
GetMenu 

SetMenu 
DrawMenuBar 


GetSystemMenu 


HiliteMenultem 


Child Window Attributes 


GetDigCtrlID 


attached to the handle, a temporary CWnd object 
is created and attached. 


Called automatically by the CWinApp idle-time 
handler and deletes any temporary CWnd objects 
created by FromHandle. 


Returns m_ hWnd, or NULL if this is NULL. 


Sends a message to the CWnd object and does not 
return until it has processed the message. 


Places a message in the CWnd object’s applica- 
tion queue, then returns without waiting for the ob- 
ject to process the message. 


Sets the CWnd text or caption title (if one exists) 
to the specified text. 


Copies the CWnd text or caption title (if it has 
one) into a buffer. 


Returns the length of the CWnd text or caption 
title. 


Sets the current font. 


Retrieves the current font. 


Retrieves a pointer to the menu. 
Sets the menu to the specified menu. 
Redraws the menu bar. 


Allows the application to access the Control menu 
for copying and modification. 


Highlights or removes the highlighting from a top- 
level (menu-bar) menu item. 


If the CWnd is a child window, calling this func- 
tion returns its ID value. 
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Window Size and Position 


CloseWindow Minimizes CWnd. 
Openlcon Activates and restores a minimized (iconic) CWnd. 
IsIconic Determines whether CWnd is minimized (iconic). 
IsZoomed Determines whether CWnd is maximized. 
MoveWindow Changes the position and/or dimensions of CWnd. 
SetWindowPos Changes the size, position, and ordering of child, 
pop-up, and top-level windows. 
ArrangelIconicWindows Arranges all the minimized (iconic) child windows. 
BringWindowToTop Brings CWnd to the top of a stack of overlapping 
windows. 
Get WindowRect Gets the screen coordinates of CWnd. 
GetClientRect Gets the dimensions of the CWnd client area. 


Coordinate Mapping Functions 


ClientToScreen Converts the client coordinates of a given point or 
rect on the display to screen coordinates. 


ScreenToClient Converts the screen coordinates of a given point 
or rect on the display to client coordinates. 


Update/Painting Functions 


BeginPaint Prepares CWnd for painting and fills a 
PAINTSTRUCT data structure with information 
about the painting. 

EndPaint Marks the end of painting. 

GetDC Retrieves a display context for the client area. 

GetWindowDC Retrieves the display context for the whole win- 
dow, including the caption bar, menus, and scroll 
bars. 

ReleaseDC Releases common and window device contexts, 
freeing them for use by other applications. 

UpdateWindow Updates the client area. 

SetRedraw Allows changes in CWnd to be redrawn or pre- 


vents changes from being redrawn. 


GetUpdateRect Retrieves the coordinates of the smallest rectangle 
that completely encloses the CWnd update region. 


648 


CWnd 


GetUpdateRgen 
Invalidate 


InvalidateRect 
InvalidateRgn 
ValidateRect 


ValidateRgen 


Show Window 
IsWindow Visible 
ShowOwnedPopups 


Timer Functions 
SetTimer 


KillTimer 


Window State Functions 
IsWindowEnabled 


EnableWindow 
GetActiveWindow 
SetActiveWindow 
GetCapture 
SetCapture 


GetFocus 


SetFocus 
SetSysModal Window 
GetSysModal Window 
GetDesktopWindow 


Retrieves the CWnd update region. 
Invalidates the entire client area. 


Invalidates the client area within the given rec- 
tangle by adding that rectangle to the update region. 


Invalidates the client area within the given region 
by adding it to the current update region. 


Validates the client area within the given rectangle 
by removing the rectangle from the update region. 


Validates the client area within the given region 
by removing the region from the current update 
region. 


Shows or hides CWnd. 
Determines if the window is visible. 


Shows or hides all pop-up windows associated 
with the window. 


Installs a system timer that sends a WM_ TIMER 
message when triggered. 


Kills a system timer. 


Determines if the window is enabled for mouse 
and keyboard input. 


Enables or disables mouse and keyboard input. 
Retrieves the active window. 


Activates the window. 


_ Retrieves the CWnd that has the mouse capture. 


Causes all subsequent mouse input to be sent to the 
CWnhd. 


Retrieves the CWnd that currently has the input 
focus. 


Assigns the input focus. 
Makes CWnd a system-modal window. 
Retrieves the system-modal CWnd if there is one. 


Retrieves the Windows desktop window. 


CWnd 649 


Dialog-Box Item Functions 


CheckDigButton 


CheckRadioButton 


GetChecked RadioButton 


DigDirList 
DigDirListComboBox 


DigDirSelect 
DigDirSelectComboBox 


GetDigItem 
GetDigItemInt 
GetDlgItemText 
GetNextDlgGroupItem 


GetNextDigTabItem 


IsDigButtonChecked 


SendDlgItemMessage 
SetDigItemInt 


SetDigIitemText 


Places a check mark next to or removes a check 
mark from a button control, or dims the button. 


Checks the specified radio button and removes the 
check mark from all other radio buttons in the 
specified group of buttons. 


Returns the ID of the currently checked radio but- 
ton in a group of buttons. 


Fills a list box with a file or directory listing. 


Fills the list box of a combo box with a file or 
directory listing. 


Retrieves the current selection from a list box. 


Retrieves the current selection from the list box of 
a combo box. 


Retrieves the handle of a control contained in the 
specified dialog box. 


Translates the text of a control in the given dialog 
box to an integer value. 


Retrieves the caption or text associated with a 
control. 


Searches for the previous (or next) control within a 
group of controls. 


Retrieves the first control that has the 
WS_TABSTOP style and precedes (or follows) 
the specified control. 


Determines whether a button control has a check 
mark next to it, and whether a three-state button 
control is dimmed, checked, or neither. 


Sends a message to the specified control. 


Sets the text of a control to the string that repre- 
sents an integer value. 


Sets the caption or text of a control in the specified 
dialog box. 
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Scrolling Functions 


GetScrollPos Retrieves the current position of a scroll box. 

GetScrollRange Copies the current minimum and maximum scroll- 
bar positions for the given scroll bar. 

ScrollWindow Scrolls CWnd. 

SetScrollPos Sets the current position of a scroll box and, if 
specified, redraws the scroll bar to reflect the new 
position. 

SetScrollRange Sets minimum and maximum position values for 


the given scroll bar. 


ShowScrollBar Displays or hides a scroll bar. 


Window Access Functions 


ChildWindowFromPoint Determines which, if any, of the child windows 
contains the specified point. 


Find Window Returns the handle of the window, which 1s iden- 
tified by its window name and class. 

GetNextWindow Searches for the next (or previous) window in the 
window-manager’s list. 

GetTopWindow Searches for a top-level child window that belongs 
to the CWnd. 

Get Window Searches for the specified window from the win- 
dow-manager’s list. 

GetLastActivePopup Determines which pop-up window owned by 
CWnd was most recently active. 

IsChild Indicates whether CWnd is a child window or 
other direct descendant of the specified window. 

GetParent Retrieves the parent window of CWnd (if any). 

SetParent Changes the parent window. 


WindowFromPoint Identifies the window that contains the given point. 


Alert Functions 
Flash Window 


MessageBox 


Clipboard Functions 
ChangeClipboardChain 


SetClipboard Viewer 


OpenClipboard 


GetClipboardOwner 


GetClipboard Viewer 


Caret Functions 
CreateCaret 


CreateSolidCaret 
CreateGrayCaret 
GetCaretPos 


SetCaretPos 
HideCaret 


ShowCaret 
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Flashes the window once. 


Creates and displays a window that contains an 
application-supplied message and caption. 


Removes CWnd from the chain of Clipboard 
viewers. 


Adds CWnd to the chain of windows that are 
notified whenever the contents of the Clipboard 
are changed. 


Opens the Clipboard. Other applications will not 
be able to modify the Clipboard until the 
CloseClipboard Windows function is called. 


Retrieves a pointer to the current owner of the 
Clipboard. 


Retrieves a pointer to the first window in the chain 
of Clipboard viewers. 


Creates a new shape for the system caret and gets 
ownership of the caret. 


Creates a solid block for the system caret and gets 
ownership of the caret. 


Creates a gray block for the system caret and gets 
ownership of the caret. 


Retrieves the client coordinates of the caret’s cur- 
rent position. 


Moves the caret to a specified position. 


Hides the caret by removing it from the display 
screen. 


Shows the caret on the display at the caret’s cur- 
rent position. Once shown, the caret begins flash- 
ing automatically. 
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Message Handlers 


(require entry in Message Map) 


OnCommand 


OnActivate 


OnActivateApp 


OnCancelMode 


OnChildActivate 
OnClose 
OnCreate 
OnCtlColor 
OnDestroy 
OnEnable 
OnEndSession 


OnEnterIdle 


OnEraseBkgend 
OnGetMinMaxInfo 


OnIconEraseBkgnd 


Called when the user selects an item from a menu, 
when a control calls its parent’s message handler, 
or when an access keystroke is translated. 


Called when CWnd is being activated or 
deactivated. 


Called when CWnd is about to be activated and 
CWhnd belongs to a different task than the cur- 
rently active window. 


Called to allow CWnd to cancel any internal 
modes, such as mouse capture, if CWnd has the 
focus when a dialog box or message box is dis- 
played. 


Called whenever the size or position of CWnd 
changes if CWnd is a child window. 


Called as a signal that CWnd or an application 
will terminate. 


Called when an application requests that CWnd be 
created. 


Called when the control or message box is about to 
be drawn if CWnd is the parent of a system- 
defined control class or a message box. 


Called when CWnd is being destroyed. 


Called when an application changes the enabled 
state of CWnd. 


Called when the session is ending. 


Called to inform an application’s main window 
procedure that a modal dialog box or a menu is en- 
tering an idle state. 


Called when the background needs erasing. 


Called whenever Windows needs to know the max- 
imized position or dimensions, or the minimum or 
maximum tracking size. 


Called when CWnd is being minimized (made 
iconic) and the background of the icon must be 
filled before painting the icon. 


OnKillFocus 
OnMenuChar 
OnMenuSelect 
OnMove 
OnPaint 
OnPaintIcon 


OnParentNotify 


OnQueryDragicon 


OnQueryEndSession 


OnQueryNewPalette 
OnQueryOpen 


OnSetFocus 
OnShow Window 
OnSize 


Nonclient-Area Functions 


OnNcActivate 
OnNcCalcSize 
OnNcCreate 


OnNcDestroy 
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Called immediately before CWnd loses the input 
focus. 


Called when the user presses a menu mnemonic 
character that doesn’t match any of the predefined 
mnemonics in the current menu. 


Called when the user selects a menu item. 


Called after the position of CWnd has been 
changed. 


Called when Windows or an application makes a 
request to repaint a portion of the window. 


Called when CWnd is minimized (iconic) and the 
icon 1s to be painted. 


Called when a CWnd child window is created or 
destroyed, or when the user clicks a mouse button 
while the cursor 1s over the child window. 


Called when a minimized (iconic) CWnd is about 
to be dragged by the user Gf CWnd does not have 
an icon defined for its class). 


Called when the user chooses to end the Windows 
session, or when an application calls the 
ExitWindows Windows function. 


Informs CWnd that it is about to receive the input 
focus. 


Called when CWnd is an icon, and the user re- 
quests that the icon be opened. 


Called after CWnd gains the input focus. 
Called when CWnd is to be hidden or shown. 
Called after the size of CWnd has changed. 


Called when the nonclient area needs to be 
changed to indicate an active or inactive state. 


Called when the size of the client area needs to be 
calculated. 


Called prior to OnCreate when the nonclient area 
is being created. 


Called when the nonclient area is being destroyed. 
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OnNcHitTest 


OnNcLButtonDbIClk 


OnNcLButtonDown 


OnNcLButtonUp 


OnNcMButtonDbICIk 


OnNcMButtonDown 


OnNcMButtonUp 


OnNcMouseMove 


OnNcPaint 
OnNcRButtonDbIClk 


OnNcRButtonDown 


OnNcRButtonUp 


Called by Windows every time the mouse is 
moved if CWnd contains the cursor, or has cap- 
tured mouse input with SetCapture. 


Called when the user double-clicks the left mouse 
button while the cursor is within a nonclient area 
of CWnd. 


Called when the user presses the left mouse button 
while the cursor is within a nonclient area of 
CWnd. 


Called when the user releases the middle mouse 
button while the cursor is within a nonclient area 
of CWnd. 


Called when the user double-clicks the middle 
mouse button while the cursor is within a nonclient 
area of CWnd. 


Called when the user presses the middle mouse 
button while the cursor is within a nonclient area 
of CWnd. 


Called when the user releases the middle mouse 
button while the cursor is within a nonclient area 
of CWnd. 


Called when the cursor is moved within a non- 
client area of CWnd. 


Called when the nonclient area needs painting. 


Called when the user double-clicks the right mouse 
button while the cursor is within a nonclient area 
of CWnd. 


Called when the user presses the right mouse but- 
ton while the cursor is within a nonclient area of 


CWnd. 


Called when the user releases the right mouse but- 
ton while the cursor is within a nonclient area of 
CWnd. 


System Message Handlers 


OnSysChar 


OnSysCommand 


Called when a keystroke translates to a system 
character. 


Called when the user selects a command from the 
Control menu, or when the user selects the Maxi- 
mize or Minimize button. 


OnSysDeadChar 
OnSysKeyDown 
OnSysKeyUp 
OnCompacting 
OnDevModeChange 
OnFontChange 
OnPaletteChanged 


OnSpoolerStatus 


OnSysColorChange 
OnTimeChange 
OnWinIniChange 

Input Message Handlers 
OnChar 

OnDeadChar 

OnHScroll 


OnKeyDown 


OnKeyUp 
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Called when a keystroke translates to a system 
dead character (such as accent characters). 


Called when the user holds down the ALT key and 
then presses another key. 


Called when the user releases a key that was 
pressed while the ALT key was held down. 


Called when Windows detects that system memory 
is low. 


Called for all top-level windows when the user 
changes device-mode settings. 


Called when the pool of font resources changes. 


Called to allow windows that don’t have the input 
focus and use a color palette to realize their logical 
palettes and update their client areas. 


Called from Print Manager whenever a job is 
added to or removed from the Print Manager 
queue. 


Called for all top-level windows when a change is 
made in the system color setting. 


Called for all top-level windows after the system 
time changes. 


Called for all top-level windows after the 
Windows initialization file, WIN.INI, is changed. 


Called when a keystroke translates to a nonsystem 
character. 


Called when a keystroke translates to a nonsystem 
dead character (such as accent characters). 


Called when the user clicks the horizontal scroll 
bar of CWnd. 


Called when a nonsystem key is pressed. A nonsys- 
tem key is a keyboard key that is pressed when the 
ALT Key is not pressed, or a keyboard key that is 
pressed when CWnd has the input focus. 


Called when a nonsystem key is released. A non- 
system key is a keyboard key that is pressed when 
the ALT key is not pressed, or a keyboard key that 
is pressed when CWnd has the input focus. 
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OnLButtonDbIClk 


OnLButtonDown 
OnLButtonUp 


OnMButtonDbIClk 
OnMButtonDown 
OnMButtonUp 
OnMouseActivate 


OnMouseMove 
OnRButtonDbIClik 


OnRButtonDown 
OnRButtonUp 
OnSetCursor 


OnTimer 
OnVScroll 


Called when the user double-clicks the left mouse 
button. 


Called when the user presses the left mouse button. 


Called when the user releases the left mouse 
button. 


Called when the user double-clicks the middle 
mouse button. 


Called when the user presses the middle mouse 
button. 


Called when the user releases the middle mouse 
button. 


Called when the cursor is in an inactive window 
and the user presses a mouse button. 


Called when the mouse cursor moves. 


Called when the user double-clicks the right mouse 
button. 


Called when the user presses the right mouse 
button. 


Called when the user releases the right mouse 
button. 


Called if mouse input is not captured and the 
mouse causes cursor movement within a window. 


Called after each interval specified in SetTimer. 


Called when the user clicks the window’s vertical 
scroll bar. 


Initialization Message Handlers 


OnInitMenu 
OniInitMenuPopup 


Called when a menu is about to become active. 


Called when a pop-up menu is about to become 
active. 


Clipboard Message Handlers 


OnAskCbFormatName 


OnChangeCbChain 


Called by a Clipboard viewer application when a 
Clipboard owner will display the Clipboard con- 
tents. 


Notifies that a specified window is being removed 
from the chain. 


OnDestroyClipboard 
OnDrawClipboard 
OnHScroliClipboard 
OnPaintClipboard 
OnRenderAllFormats 


OnRenderFormat 


OnSizeClipboard 


OnVScrollClipboard 
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Called when the Clipboard is emptied through a 
call to the EmptyClipboard Windows function. 


Called when the contents of the Clipboard change. 


Called when a Clipboard owner will scroll the 
Clipboard image, invalidate the appropriate sec- 
tion, and update the scroll-bar values. 


Called when the client area of the Clipboard 
viewer needs repainting. 


Called when the owner application is being de- 
stroyed and needs to render all its formats. 


Called for the Clipboard owner when a particular 
format with delayed rendering needs to be ren- 
dered. 


Called when the size of the client area of the 
Clipboard-viewer window has changed. 


Called when the owner should scroll the Clipboard 
image, invalidate the appropriate section, and up- 
date the scroll-bar values. 


Control Message Handlers 


OnCharTolItem 


OnCompareltem 


OnDeleteItem 


OnDrawlItem 


OnGetDligCode 


Called by a child list box with the 
LBS_WANTKEYBOARDINPUT style in 
response to a WM_ CHAR message. 


Called to determine the relative position of a new 
item in a sorted owner-draw combo or list box. 


Called when an owner-draw list box or combo box 
is destroyed or when items are removed from the 
control by calls to CComboBox::DeleteString or 
CComboBox::ResetContent. 


Called when a visual aspect of an owner-draw but- 
ton control, combo box control, list box control, or 
menu needs to be drawn. 


Called for a control so the control can process 
ARROW key and TAB key input itself, although 
Windows normally handles this input. 
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OnMeasurelItem 


OnVKeyTolItem 


MDI Message Handlers 
OnMDIActivate 


Protected Members 


Initialization 
CreateEx 


Operations 
GetCurrentMessage 


GetSuper WndProcAddr 


PreTranslateMessage 


WindowProc 


Default 


DefWindowProc 


Called for an owner-draw button, combo box, list 
box, or menu item when the control is created. 
CWnd informs Windows of the dimensions of the 
control. 


Called by a list box owned by CWnd in response 
toa WM_KEYDOWN message. 


Called when an MDI child window is activated or 
deactivated. 


Creates a Windows overlapped, pop-up, or child 
window and attaches it to a CWnd object. 


Returns a pointer to the message this window is 
currently processing. Should only be called when 
in an OnMessage message handler member 
function. 


Accesses the original WndProc address of a sub- 
classed window, and is used for translating 
Windows messages in the main message handler. 


Used by CWinApp to filter window messages 
before they are dispatched to TranslateMessage 
and DispatchMessage. 


Provides a window procedure for a CWnd. The de- 
fault dispatches messages through the message 
map. 


Calls the default window procedure, which pro- 
vides default processing for any window messages 
that an application does not process. 


Calls the default window procedure, which pro- 
vides default processing for any window messages 
that an application does not process. 
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Member Functions 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
Return Value 


See Also 


CWnd::ArrangelconicWindows 


UINT ArrangelIconicWindows(); 


Arranges all the minimized (iconic) child windows. 


This member function also arranges icons on the desktop window, which covers 
the entire screen. The GetDesktopWindow member function retrieves a pointer to 
the desktop window object. 


To arrange iconic MDI child windows in an MDI client window, call 
CMDIFrameWnd::MDIIconArrange. 


The height of one row of icons, or 0 if there were no icons. 


CWnd::GetDesktopWindow, CMDIFrameWnd::MDIIconArrange, 
::ArrangelconicWindows 


CWnd::Attach 


BOOL Attach( HWND hWndNew ); 


hWndNew 
Specifies a handle to a Windows window. 


Attaches a Windows window to a CWnd object. 
TRUE if the operation was successful; otherwise FALSE. 


CWnd::Detach, CWnd::~CWnd, CWnd::m_hWnd 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CWnd::BeginPaint 
CDC* BeginPaint( LPPAINTSTRUCT /pPaint ); 


[pPaint 
Points to the PAINTSTRUCT structure that is to receive painting information. 


Prepares CWnd for painting and fills a PAINTSTRUCT data structure with infor- 
mation about the painting. 


The paint structure contains a RECT data structure that has the smallest rectangle 
that completely encloses the update region, and a flag that specifies whether the 
background has been erased. 


The update region is set by the Invalidate, InvalidateRect, or InvalidateRgn 
member functions and by the system after sizing, moving, creating, scrolling, or 
any other operation that affects the client area. If the update region is marked for 
erasing, BeginPaint sends an WM_ONERASEBKGND message. 


Do not call the BeginPaint member function except in response to a 

WM_ PAINT message. Each call to the BeginPaint member function must have a 
matching call to the EndPaint member function. If the caret is in the area to be 
painted, the BeginPaint member function automatically hides the caret to prevent 
it from being erased. 


Identifies the device context for CWnd. The pointer may be temporary, and 
should not be stored beyond the scope of EndPaint. 


CWnd::EndPaint, CWnd::Invalidate, CWnd::InvalidateRgn, ::BeginPaint, | 
CPaintDC 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


CWnd::CheckDigButton 


CWnd::BringWindowToTop 


void BringWindowToTopQ); 


Brings CWnd to the top of a stack of overlapping windows. In addition, 
Bring WindowToTop activates pop-up and top-level windows. The 

BringWindowToTop member function should be used to uncover any window 
that is partially or completely obscured by any overlapping windows. 


::BringWindowToTop 


CWnd::ChangeClipboardChain 


BOOL ChangeClipboardChain( HWND hWndNext ); 


hWndNext 
Identifies the window that follows CWnd in the Clipboard-viewer chain. 


Removes CWnd from the chain of Clipboard viewers and makes the window 
specified by hWndNext the descendant of the CWnd ancestor in the chain. 


TRUE if CWnd is removed; otherwise FALSE. 


CWnd::SetClipboard Viewer, ::ChangeClipboardChain 


CWnd::CheckDIgButton 


void CheckDlgButton( int n/DButton, UINT nCheck ); 


nl DButton 
Specifies the button control to be modified. 


nCheck 


Specifies the action to take. If nCheck is nonzero, the CheckDigButton mem- 
ber function places a check mark next to the button; if 0, the check mark 1s re- 
moved. For three-state buttons, if nCheck is 2, the button is dimmed; if nCheck 


is 1, it is checked; if nCheck is 0, the check mark is removed. 
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Remarks 


See Also 


syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


Places a check mark next to or removes a check mark from a button control, or, 
for a three-state button, may dim the button. 


CWnd::IsDigButtonChecked, ::CheckDlgButton 


CWnd::CheckRadioButton 


void CheckRadioButton( int n/DFirstButton, int nIDLastButton, 
int nI1DCheckButton ); 


nlD FirstButton 
Specifies the integer identifier of the first radio button in the group. 


nIDLastButton 
Specifies the integer identifier of the last radio button in the group. 


nIDCheckButton 
Specifies the integer identifier of the radio button to be checked. 


Checks the radio button specified by nJ[DCheckButton and removes the check 
mark from all other radio buttons in the group of buttons specified by 
niIDFirstButton and nIDLastButton. Checking a radio button turns the radio button 
on or off. 


CWnd::GetChecked RadioButton, ::CheckRadioButton 


CWnhd::ChildWindowFromPoint 


CWnd* ChildWindowFromPoint( POINT point ) const; 


point 
Specifies the client coordinates of the point to be tested. 


Determines which, if any, of the child windows belonging to CWnd contains the 
specified point. 


Identifies the child window that contains the point. It is NULL if the given point 
lies outside of the client area. If the point is within the client area but is not con- 
tained within any child window, CWnd is returned. 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


CWnd::ClientToScreen 663 


This member function will return a hidden or disabled child window that contains 
the specified point. 


The CWnd* that is returned may be temporary, and should not be stored beyond 
its immediate use. 


CWnd:: WindowFromPoint, ::ChildWindowFromPoint 


CWnd::ClientToScreen 


void ClientToScreen( LPPOINT /pPoint ) const; 


void ClientToScreen( LPRECT /pRect ) const; 


lpPoint 
Points to a POINT structure or CPoint that contains the client coordinates to 
be converted. 


lpRect 
Points to a RECT structure or CRect that contains the client coordinates to be 
converted. | 


Converts the client coordinates of a given point or rectangle on the display to 
screen coordinates. The ClientToScreen member function uses the client coordi- 
nates in the POINT or RECT structure, or CPoint or CRect pointed to by /pPoint 
or /pRect, to compute new screen coordinates; it then replaces the coordinates in 
the structure with the new coordinates. The new screen coordinates are relative to 
the upper-left corner of the system display. 


The ClientToScreen member function assumes that the given point or rectangle is 
in client coordinates. 


CWnd::ScreenToClient, ::ClientToScreen 
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Syntax 


Remarks 


See Also 


Syntax 


Parameters 


CWnd::CloseWindow 


void CloseWindow(); 


Minimizes CWnd. If CWnd is an overlapped window, it is minimized by remov- 
ing the client area and caption of the open window from the display screen and 
moving its icon into the icon area of the screen. 


This member function has no effect if CWnd is a pop-up or child window. 


CWnd::Opentcon, ::CloseWindow 


CWnd::Create 


BOOL Create( const char FA R* /pClassName, 
const char FAR* /pWindowName, DWORD dwSvbyle, const RECT & rect, 
const CWnd* pParentWnd, UINT nID ); 


lpClassName 
Points to a null-terminated character string that names the Windows class (a 
WNDCLASS struct). The class name can be any name registered with the 
AfxRegisterWndClass function or any of the predefined control-class names. 
If NULL, uses the default CWnd attributes. See CreateEx for a description of 
the possible values. 


lp WindowName 
Points to a null-terminated character string that contains the window name. 


dwStyle 
Specifies the window style attributes. See CreateEx for a description of the 
possible values. 


rect 
The size and position of the window, in client coordinates of pParentWnd. 


pParentWnd 
The parent window. 


nID 
The ID of the child window. 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


~Remarks 


See Also 


CWnd::CreateCaret 665 


Creates a Windows child window and attaches it to the CWnd object. 


You construct a child window in two steps. First, invoke the constructor, which 
constructs the CWnd object, then call Create, which creates the Windows child 
window and attaches it to CWnd. Create initializes the window’s class name and 
window name, and registers values for its style, parent, and ID. 


TRUE if initialization is successful; otherwise FALSE. 


CWnd::CWnd, CWnd::CreateEx 


CWnd::CreateCaret 


void CreateCaret( CBitmap* pBitmap ); 


pBitmap 
Identifies the bitmap that defines the caret shape. 


Creates a new shape for the system caret and claims ownership of the caret. 


The bitmap must have previously been created by using the 
CBitmap::CreateBitmap member function, CreateDIBitmap Windows func- 
tion, or the CBitmap::LoadBitmap member function. 


Automatically destroys the previous caret shape, if any, regardless of which win- 
dow owns the caret. Once created, the caret is initially hidden. To show the caret, 
the ShowCaret member function must be called. The system caret is a shared re- 
source. CWnd should create a caret only when it has the input focus or is active. It 
should destroy the caret before losing the input focus or becoming inactive. 


CBitmap::CreateBitmap, ::CreateDIBitmap, ::DestroyCaret, 
CBitmap::LoadBitmap, CWnd::ShowCaret, ::CreateCaret 
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CWnd::CreateEx 


Syntax Protected: 
BOOL CreateEx( DWORD dwExStyle, const char FAR* /pClassName, 
const char FAR* /pWindowName, DWORD dwSvble, int x, int y, int nWidth, 
int nHeight, HWND hwndParent, HMENU nlDorHMenu ); 


Parameters dwExStyle 

| Specifies the extended style of the CWnd being created. It may be one of the 
following values: 
Style Meaning 


WS_EX_DLGMODALFRAME __ Designates a window with a double 
border that may optionally be created 
with a title bar by specifying the 
WS_CAPTION style flag in dwStyle. 


WS_EX_NOPARENTNOTIFY — Specifies that a child window created 
with this style will not send the 
WM_PARENTNOTIFY message to 
its parent window when the child 
window is created or destroyed. 


WS_EX_ TOPMOST Specifies that a window created with 
this style should be placed above all 
nontopmost windows and stay above 
them even when CWnd is deac- 
tivated. An application can use the 
SetWindowPos member function to 
add or remove this attribute. 


[pClassName 
Points to a null-terminated character string that names the Windows class (a 
WNDCLASS struct). The class name can be any name registered with the 
AfxRegisterWndClass function or any of the predefined control-class names. 
It must not be NULL. 


lp WindowName 
Points to a null-terminated character string that contains the window name. 


Remarks 
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dwStyle 
Specifies the Windows style of CWnd. 


x 
Specifies the initial x-position of the CWnd window. 


Specifies the initial top position of the CWnd window. 


nWidth 
Specifies the width (in device units) of the CWnd window. 


nHeight 
Specifies the height (in device units) of the CWnd window. 


hwndParent 
Identifies the parent or owner window of the CWnd window being created. 
Use NULL for top-level windows. 


nlDorHMenu 
Identifies a menu or a child-window identifier. The meaning depends on the 
style of the window. 


Creates an overlapped, pop-up, or child window with the extended style specified 
in dwExStyle. 


The CreateEx parameters specify the WNDCLASS, window title, window style, 
and (optionally) initial position and size of the window. CreateEx also specifies 
the window’s parent (if any) and ID. 


When CreateEx executes, Windows sends the WM_GETMINMAXINFO, 
WM_NCCREATE, WM_NCCALCSIZE, and WM_CREATE messages to 
the window. 


To extend the default message handling, derive a class from CWnd, add a mes- 
Sage map to the new class, and provide member functions for the above messages. 
Override OnCreate, for example, to perform needed initialization for a new class. 


Override further OnMessage message handlers to add further functionality to your 
derived class. 


If the WS_ VISIBLE style is given, Windows sends the window all the messages 
required to activate and show the window. If the window style specifies a title bar, 
the window title pointed to by the Jp WindowName parameter is displayed in the 
title bar. 
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The dwStyle parameter can be any combination of the following window styles. 


Style 
DS_LOCALEDIT 


DS_MODALFRAME 


DS_NOIDLEMSG 


DS_SYSMODAL 
WS_ BORDER 
WS_ CAPTION 


WS_ CHILD 


WS_CHILDWINDOW 
WS_CLIPCHILDREN 


Meaning 


Specifies that edit controls in the dialog 
box will use memory in the application’s 
data segment. By default, all edit controls 
in dialog boxes use memory outside the 
application’s data segment. This feature 
may be suppressed by adding the 
DS_LOCALEDIT flag to the Style 
command for the dialog box. If this flag is 
not used, EM_GETHANDLE and 
EM_SETHANDLE messages must not be 
used since the storage for the control is not 
in the application’s data segment. This 
feature does not affect edit controls created 
outside of dialog boxes. 


Creates a dialog box with a modal dialog- 
box frame that can be combined with a title 
bar and Control menu by specifying the 
WS_ CAPTION and WS_SYSMENU 
styles. 


Suppresses WM_ENTERIDLE messages 
that Windows would otherwise send to the 
owner of the dialog box while the dialog 
box is displayed. 


Creates a system-modal dialog box. 
Creates a window that has a border. 


Creates a window that has a title bar 
(implies the WS_ BORDER style). This 
style cannot be used with the 
WS_DLGFRAME style. 


Creates a child window. Cannot be used 
with the WS_POPUP style. 


Same as the WS_ CHILD style. 


Excludes the area occupied by child 
windows when drawing within the parent 
window. Used when creating the parent 
window. 


Style 
WS_CLIPSIBLINGS 


WS_ DISABLED 
WS_DLGFRAME 


WS_GROUP 


WS_HSCROLL 


WS_iCONIC 
WS_MAXIMIZE 
WS_MAXIMIZEBOX 
WS_MINIMIZE 


WS_MINIMIZEBOX 
WS_OVERLAPPED 


CWnd::CreateEx 


Meaning 


Clips child windows relative to each other; 
that is, when a particular child window 
receives a paint message, the 
WS_CLIPSIBLINGS style clips all other 
overlapped child windows out of the region 
of the child window to be updated. (If 
WS_CLIPSIBLINGS is not given and 
child windows overlap, it is possible, when 
drawing within the client area of a child 
window, to draw within the client area of a 
neighboring child window.) For use with 
the WS_ CHILD style only. 


Creates a window that is initially disabled. 


Creates a window with a double border but 
no title. 


Specifies the first control of a group of 
controls in which the user can move from 
one control to the next by using the ARROW 
keys. All controls defined with the 
WS_GROUP style after the first control 
belong to the same group. The next control 
with the WS_GROUP style ends the style 
group and starts the next group (that is, one 
group ends where the next begins). Only 
dialog boxes use this style. 


Creates a window that has a horizontal 
scroll bar. 


Same as the WS_MINIMIZE style. 
Creates a window of maximum size. 
Creates a window that has a maximize box. 


Creates a window that is initially 
minimized. For use with the 
WS_OVERLAPPED style only. 


Creates a window that has a minimize box. 


Creates an overlapped window. An 
overlapped window has a caption and a 
border. 
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Return Value 


See Also 


Style 
WS_OVERLAPPEDWINDOW 


WS_ POPUP 


WS_POPUPWINDOW 


WS_SIZEBOX 
WS_SYSMENU 


WS_TABSTOP 


WS_THICKFRAME 


WS_ TILED 
WS_TILEDWINDOW 


WS_ VISIBLE 


WS_VSCROLL 


Meaning 


Creates an overlapped window having the 
WS_OVERLAPPED, WS_ CAPTION, 
WS_SYSMENU, WS_THICKFRAME, 
WS_MINIMIZEBOX, and 
WS_MAXIMIZEBOxX styles. 


Creates a pop-up window. Cannot be used 
with the WS_ CHILD style. 


Creates a pop-up window that has the 
WS_ BORDER, WS_ POPUP, and 
WS_SYSMENU styles. The 
WS_CAPTION style must be combined 
with the WS_POPUPWINDOW style to 
make the Control menu visible. 


Same as the WS_ THICKFRAME style. 


Creates a window that has a Control-menu 
box in its title bar. Used only for windows 
with title bars. 


Specifies one of any number of controls 
through which the user can move by using 
the TAB key. The TAB key moves the user to 
the next control specified by the 
WS_TABSTOP style. Only dialog boxes 
use this style. 


Creates a window with a thick frame that 
can be used to size the window. 


Same as the WS_ OVERLAPPED style. 


Same as the 
WS_OVERLAPPEDWINDOW< style. 


Creates a window that is initially visible. 
This applies to overlapped and pop-up 
windows. 


Creates a window that has a vertical scroll 
bar. 


TRUE if the CWnd window is created; otherwise FALSE. 


::CreateWindowEx 


Syntax 


Parameters 


Remarks 


See Also 


CWnd::CreateGrayCaret _—_671 


CWnd::CreateGrayCaret 


void CreateGrayCaret( int nWidth, int nHeight ); 


nWidth 
Specifies the width of the caret (in logical units). If this parameter is O, the 
width is set to the system-defined window-border width. 


nHeight 
Specifies the height of the caret (in logical units). If this parameter is 0, the 
height is set to the system-defined window-border height. 


Creates a gray rectangle for the system caret and claims ownership of the caret. 
The caret shape can be a line or a block. 


The parameters nWidth and nHeight specify the caret’s width and height (in logi- 
cal units); the exact width and height (in pixels) depend on the mapping mode. 


The CreateGrayCaret member function automatically destroys the previous caret 
shape, if any, regardless of which window owns the caret. Once created, the caret 
is initially hidden. To show the caret, the ShowCaret member function must be 
called. 


The system caret is a shared resource. CWnd should create a caret only when it 
has the input focus or is active. It should destroy the caret before losing the input 
focus or becoming inactive. 


The system’s window-border width or height can be retrieved by using the 
GetSystemMetrics Windows function with the SM_CXBORDER and 
SM_CYBORDER indexes. Using the window-border width or height ensures 
that the caret will be visible on a high-resolution display. 


::DestroyCaret, ::GetSystemMetrics, CWnd::ShowCaret, ::CreateCaret 
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syntax 


Parameters 


Remarks 


See Also 


CWnd::CreateSolidCaret 


void CreateSolidCaret( int n Width, int nHeight ); 


nWidth 
Specifies the width of the caret (in logical units). If this parameter is 0, the 
width is set to the system-defined window-border width. 


nHeight 
Specifies the height of the caret (in logical units). If this parameter is 0, the 
height is set to the system-defined window-border height. 


Creates a solid rectangle for the system caret and claims ownership of the caret. 
The caret shape can be a line or block. 


The parameters nWidth and nHeight specify the caret’s width and height (in logi- 
cal units); the exact width and height (in pixels) depend on the mapping mode. 


The CreateSolidCaret member function automatically destroys the previous caret 
shape, if any, regardless of which window owns the caret. Once created, the caret 
is initially hidden. To show the caret, the ShowCaret member function must be 
called. 


The system caret is a shared resource. CWnd should create a caret only when it 
has the input focus or is active. It should destroy the caret before losing the input 
focus or becoming inactive. 


The system’s window-border width or height can be retrieved by using the 
GetSystemMetrics Windows function with the SM_CXBORDER and 
SM_CYBORDER indexes. Using the window-border width or height ensures 
that the caret will be visible on a high-resolution display. 


::DestroyCaret, ::GetSystemMetrics, CWnd::ShowCaret, ::CreateCaret 


Syntax 


Remarks 


See Also 


Syntax 
Remarks 


See Also 


Syntax 


Remarks 


Return Value 


See Also 
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CWnd::CWnd 


CWnd(); 


Constructs a CWnd object. The Windows window is not created and attached 
until the CreateEx or Create member function is called. 


CWnd::CreateEx, CWnd::Create, CWnd::~CWnd 


CWnd::~CWnd 


virtual ~CWnd(); 
Destroys a CWnd object and destroys the attached window. 


CWnd::CWnd, CWnd::Destroy Window 


CWnd::Default 


protected: LONG Default(); 

Calls the default window procedure. The default window procedure provides de- 
fault processing for any window message that an application does not process. 
This member function is used to ensure that every message is processed. All 
CWnd OnMessage member functions call this member function. 


Depends on the message that was passed to this function. 


::DefDlgProc, CWnd::DefWindowProc, ::DefWindowProc 


674 CWnd::DefWindowProc 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


CWnd::DefWindowProc 


Protected: 
virtual LONG DefWindowProc( UINT message, UINT wParam, 
LONG /Param ); 


message 
Specifies the Windows message to be processed. 


wParam 
Specifies 16 bits of additional message-dependent information. 


[Param 
Specifies 32 bits of additional message-dependent information. 


Calls the default window procedure, which provides default processing for any 
window message that an application does not process. This member function is 


used to ensure that every message is processed. It should be called with the same 
parameters as those received by the window procedure. 


The source code for the DefWindowProc function is provided on the Windows 
Software Development Kit disks. 


Dependent on the message that was passed to this function. 


::DefDigProc, CWnd::Default, :: DefWindowProc 


CWnhd::DeleteTempMap 


static void DeleteTempMap(Q); 


Called automatically by the idle time handler of CWinApp, and deletes any tem- 
porary CWnd objects created by FromHandle. 


CWnd::FromHandle 


Syntax 


Remarks 


Return Value 


See Also 
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CWnd::DestroyWindow 


virtual BOOL Destroy Window(); 


Destroys the Windows window attached to CWnd. The Destroy Window member 
function sends appropriate messages to CWnd to deactivate it and remove the 
input focus. It also destroys CWnd’s menu, flushes the application queue, de- 
stroys outstanding timers, removes Clipboard ownership, and breaks the 
Clipboard-viewer chain if CWnd is at the top of the viewer chain. It sends 

WM_ DESTROY and WM_NCDESTROY messages to the window. It 

does not destroy the CWnd object. 


If CWnd is the parent of any windows, these child windows are automatically de- 
stroyed when the parent window is destroyed. The DestroyWindow member func- 
tion destroys child windows first, and then CWnad itself. 


The Destroy Window member function also destroys modeless dialog boxes 
created by the CreateDialog Windows function. 


If the CWnd being destroyed is a child window and does not have the 
WS_NOPARENTNOTIPY style set, then the WM_PARENTNOTIFY 


message is sent to the parent. 


Specifies whether the window is destroyed. It is TRUE if the window is de- 
stroyed; otherwise FALSE. 


::CreateDialog, CWnd::OnDestroy, CWnd::Detach, ::DestroyWindow 


676 CWnd::Detach 


Syntax 
Remarks 
Return Value 


See Also 


Syntax 


Parameters 


CWnd::Detach 


HWND DetachQ; 
Detaches a Windows handle from a CWnd object and returns the handle. 
A HWND to the Windows object. 


CWnd::Attach 


CWnd::DigDirList 


int DigDirList( const char FAR* /pPathSpec, int nIDListBox, int nIDStaticPath, 
UINT nFileType ); 


lpPathSpec 
Points to a path string, must be a CString or a null-terminated character string. 


nIDListBox 
Specifies the identifier of a list box control. If nJDListBox is 0, DigDirList 
assumes that no list box exists and does not attempt to fill one. 


nIDStaticPath 
Specifies the identifier of the static-text control used for displaying the current 
drive and directory. If nJDStaticPath is 0, DigDirList assumes that no such text 
control is present. 


nFileType 
Specifies the attributes of the files to be displayed. It can be any combination of 
the following values: 


Value Meaning 

0x0000 Read/write data files with no additional attributes. 
0x0001 Read-only files. 

0x0002 Hidden files. 

0x0004 System files. 

0x0010 Subdirectories. 


0x0020 Archives. 


Remarks 


Return Value 


See Also 


CWnd::DigDirList 677 


Value Meaning 


Ox2000 LB_DIR flag. If the LB_ DIR flag is set, Windows places 
the messages generated by DigDirList in the application’s 
queue; otherwise they are sent directly to the dialog function. 


0x4000 Drives. 


Ox 8000 Exclusive bit. If the exclusive bit is set, only files of the 
specified type are listed. Otherwise, files of the specified 
type are listed in addition to normal files. 


Fills a list box control with a file or directory listing. It fills the list box specified 
by nIDListBox with the names of all files matching the path given by /pPathSpec. 


The DigDirList member function shows subdirectories enclosed in square brack- 
ets ({ ]), and shows drives in the form [-x-], where x is the drive letter. 


The /pPathSpec parameter has the following form: 


[drive:] [— L\uldirectoryl\idirectory]...\u] [filename] 


In this example, drive is a drive letter, directory is a valid directory name, and 
filename is a valid filename that must contain at least one wildcard character. The 
wildcard characters are a question mark (?), meaning match any character, and an 
asterisk (*), meaning match any number of characters. 


If you specify a zero-length string for JpPathSpec or specify only a directory name 
but do not include any file specification, the string will be changed to “*.*”’, 


If [pPathSpec includes a drive and/or directory name, the current drive and 
directory are changed to the designated drive and directory before the list box is 
filled. The text control identified by n/DStaticPath is also updated with the new 
drive and/or directory name. 


After the list box is filled, JpPathSpec is updated by removing the drive and/or 
directory portion of the path. 


DigDirList sends LB_RESETCONTENT and LB_ DIR messages to the list box. 
Specifies the outcome of the function. It is nonzero if a listing was made, even an 
empty listing. A 0 return value implies that the input string did not contain a valid 


search path. 


CWnd::DigDirListComboBox, ::DigDirList 
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Syntax 


Parameters 


Remarks 


CWnd::DigDirListComboBox 


int DigDirListComboBox( const char FAR* [pPathSpec, int nIDComboBox, 
int n/DStaticPath, UINT nFileType ); 


[pPathSpec 
Points to a path string, must be a CString or a null-terminated character string. 


nIDComboBox 
Specifies the identifier of a combo box control in a dialog box. If 
nIDComboBox 1s 0, DigDirListComboBox assumes that no combo box exists 
and does not attempt to fill one. 


nI[DStaticPath 
Specifies the identifier of the static-text control used for displaying the current 
drive and directory. If n/DStaticPath is 0, DigDirListComboBox assumes that 
no such text control is present. 


nFileType 
Specifies DOS file attributes of the files to be displayed. It can be any combina- 
tion of the following values: 


Value Meaning 

Ox0000 Read/write data files with no additional attributes. 

0x0001 Read-only files. 

Ox0002 Hidden files. 

0x0004 System files. 

0x0010 Subdirectories. 

0x0020 Archives. 

0Ox2000 CB_DIR flag. If the CB_ DIR flag is set, Windows places the 


messages generated by DlgDirListComboBox in the 
application’s queue; otherwise they are sent directly to the 
dialog function. 


0x4000 Drives. 


0x8000 Exclusive bit. If the exclusive bit is set, only files of the 
specified type are listed. Otherwise, files of the specified type 
are listed in addition to normal files. 


Fills the list box of a combo box control with a file or directory listing. It fills the 
list box of the combo box specified by nJDComboBox with the names of all files 
matching the path given by /pPathSpec. | 


Return Value 


See Also 


Syntax 


Parameters 


CWnd::DigDirSelect — 679 


The DigDirListComboBox member function shows subdirectories enclosed in 
square brackets ([{ ]), and shows drives in the form [-x-], where x is the drive letter. 


The /pPathSpec parameter has the following form: 


[drive:] [ [\uldirectory[\idirectory]...\u] [filename] 


In this example, drive is a drive letter, directory is a valid directory name, and 
filename 1s a valid filename that must contain at least one wildcard character. The 
wildcard characters are a question mark (?), meaning match any character, and an 
asterisk (*), meaning match any number of characters. 


If you specify a zero-length string for /pPathSpec or if you specify only a 


directory name but do not include any file specification, the string will be changed 
to Pera, 


If IpPathSpec includes a drive and/or directory name, the current drive and 
directory are changed to the designated drive and directory before the list box is 
filled. The text control identified by n/DStaticPath is also updated with the new 
drive and/or directory name. 


After the combo box list box is filled, JpPathSpec is updated by removing the 
drive and/or directory portion of the path. 


DigDirListComboBox sends CB_RESETCONTENT and CB_ DIR messages 
to the combo box. 


Specifies the outcome of the function. It is nonzero if a listing was made, even an 
empty listing. A O return value implies that the input string did not contain a valid 


search path. 


CWnd::DigDirList, CWnd::DigDirSelect, :: DlgDirListComboBox 


CWnd::DigDirSelect 


BOOL DlgDirSelect( LPSTR /pString, int nIDListBox ); 


lpString 
Points to a buffer that is to receive the current selection in the list box. 


nIDListBox 
Specifies the integer ID of a list box control in the dialog box. 
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Remarks 


Retrieves the current selection from a list box. It assumes that the list box has been 
filled by the DigDirList member function and that the selection is a drive letter, a 
file, or a directory name. 


The DigDirSelect member function copies the selection to the buffer given by 
IpString. If the current selection is a directory name or drive letter, DigDirSelect 
removes the enclosing square brackets (and hyphens, for drive letters) so that the 
name or letter is ready to be inserted into a new path. If there is no selection, 
lpString does not change. 


DigDirSelect sends LB_GETCURSEL and LB_GETTEXT messages to the 
list box. 


The DlgDirSelect member function does not allow more than one filename to be 
returned from a list box. 


The list box must not be a multiple-selection list box. If it is, this function will not 
return a O value and /pString will remain unchanged. 


Specifies the status of the current list box selection. It is TRUE if the current selec- 
tion is a directory name; otherwise FALSE. 


CWnd::DigDirList, CWnd::DigDirListComboBox, 
CWnd::DigDirSelectComboBox, ::DlgDirSelect 


CWnd::DigDirSelectComboBox 


BOOL DlgDirSelectComboBox( LPSTR [pString, int n[DComboBox ); 


lpString 
Points to a buffer that is to receive the selected path. 


nIDComboBox 
Specifies the integer ID of the combo box control in the dialog box. 


Retrieves the current selection from the list box of a combo box. It assumes that 
the list box has been filled by the DIgDirListComboBox member function and 
that the selection is a drive letter, a file, or a directory name. 


The DigDirSelectComboBox member function copies the selection to the 
specified buffer. If the current selection is a directory name or drive letter, 
DigDirSelectComboBox removes the enclosing square brackets (and hyphens, for 
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drive letters) so that the name or letter is ready to be inserted into a new path. If 
there is no selection, the contents of the buffer are not changed. 


DigDirSelectComboBox sends CB_GETCURSEL and CB_GETLBTEXT 
messages to the combo box. 


The DilgDirSelectComboBox member function does not allow more than one 
filename to be returned from a combo box. 


Specifies the status of the current combo box selection. It is TRUE if the current 
selection is a directory name; otherwise FALSE. 


CWnd::DigDirListComboBox, ::DlgDirSelectComboBox 


CWnhd::DrawMenuBar 


void DrawMenuBar(); 


Redraws the menu bar. If a menu bar is changed after Windows has created the 
window, call this function to draw the changed menu bar. 


::DrawMenuBar 


CWnd::EnableWindow 


BOOL EnableWindow( BOOL bEnable = TRUE ); 


bEnable 
Specifies whether the given window is to be enabled or disabled. If this parame- 
ter is TRUE, the CWnd will be enabled. If this parameter is FALSE, the 
CWnd will be disabled. 


Enables or disables mouse and keyboard input. When input is disabled, input such 
as mouse clicks and keystrokes is ignored. When input is enabled, the window 
processes all input. 


If the enabled state is changing, the WM_ENABLE message is sent before this 
function returns. 
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See Also 
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See Also 


If disabled, all child windows are implicitly disabled, although they are not sent 
WM_ENABLE messages. 


CWnd must be enabled before it can be activated. For example, if an application 
is displaying a modeless dialog box and has disabled its main window, the main 
window must be enabled before the dialog box is destroyed. Otherwise, another 
window will get the input focus and be activated. If a child window is disabled, it 
is ignored when Windows tries to determine which window should get mouse 
messages. 


Initially, all windows are enabled by default. EnableWindow must be used to dis- 
able CWnd explicitly. 


Indicates the state before the EnableWindow member function was called. The re- 
turn value is TRUE if CWnd was previously enabled. The return value is FALSE 
if CWnd was previously disabled or an error occurred. 


::EnableWindow 


CWhd::EndPaint 


void EndPaint( LPPAINTSTRUCT /pPaint ); 


lpPaint 
Points toa PAINTSTRUCT structure that contains the painting information re- 
trieved by the BeginPaint member function. 


Marks the end of painting in the given window. The EndPaint member function is 
required for each call to the BeginPaint member function, but only after painting 
is complete. 


If the caret was hidden by the BeginPaint member function, EndPaint restores 
the caret to the screen. 


CWhnd::BeginPaint, ::EndPaint, CPaintDC 
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CWnd::FlashWindow 683 


CWnd::FindWindow 


static CWnd* FindWindow( const char FAR* /pClassName, 
const char FAR* [pWindowName ); 


lpClassName 
Points to a null-terminated string that specifies the window’s class name. If 
lpClassName is NULL, all class names match (a WNDCLASS struct). 


lpWindowName 
Points to a null-terminated string that specifies the window name (the window’s 
text caption). If /p>WindowName is NULL, all window names match. 


Returns the CWnd whose class is given by [pClassName and whose window 
name, or caption, is given by /pWindowName. This function does not search child 
windows. 


Identifies the window that has the specified class name and window name. It is 
NULL if no such window is found. 


The CWnd* may be temporary and should not be stored for later use. 


::FindWindow 


CWnd::FlashWindow 


BOOL FlashWindow( BOOL blnvert ); 


bInvert 
Specifies whether the CWnd is to be flashed or returned to its original state. 
The CWnd is flashed from one state to the other if b/nvert is TRUE. If binvert 
is FALSE, the window is returned to its original state (either active or inactive). 


Flashes the given window once. Flashing the CWnd means changing the appear- 
ance of its caption bar as if the CWnd were changing from inactive to active sta- 
tus, or vice versa. (An inactive caption bar changes to an active caption bar; an 
active caption bar changes to an inactive caption bar.) 
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See Also 


Typically, a CWnd is flashed to inform the user that it requires attention, but that 
it does not currently have the input focus. 


Flash Window flashes the window only once; for successive flashing, create a sys- 
tem timer and repeatedly call FlashWindow. 


The blnvert parameter should be FALSE only when CWnd is getting the input 
focus and will no longer be flashing; it should be TRUE on successive calls while 
waiting to get the input focus. 


This function always returns TRUE for iconic windows. If CWnd is iconic, 
FlashWindow will simply flash the icon; b/nvert is ignored for iconic windows. 


Specifies the state before the call to the FlashWindow member function. It is 
TRUE if CWnd was active before the call; otherwise FALSE. 


::Flash Window 


CWnd::FromHandle 


static CWnd* FromHandle( HWND hWnd ); 


hWnd 
A HWND of a Windows window. 


Returns a pointer to a CWnd object when given a handle to a window. If a CWnd 
object is not attached to the handle, a temporary CWnd object is created and at- 
tached. | 


The pointer may be temporary, and should not be stored beyond immediate use. 


CWnd::DeleteTempMap 
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See Also 


CWnd::GetCapture 685 


CWnd::GetActiveWindow 


static CWnd* GetActiveWindow(); 


Retrieves a pointer to the active CWnd. The active CWnd is either the window 
that has the current input focus, or the window explicitly made active by the 
SetActiveWindow member function. 


The active window, or NULL if no window was active at the time of the call. The 
pointer may be temporary, and should not be stored beyond immediate use. 


CWnd::SetActiveWindow, ::GetActiveWindow 


CWnd::GetCapture 


static CWnd* GetCapture(); 


Retrieves the CWnd that has the mouse capture. Only one window has the mouse 
capture at any given time. This window receives mouse input whether or not the 
cursor is within its borders. 


The CWnd receives the mouse capture when the SetCapture member function is 
called. 


Identifies the window that has the mouse capture. It is NULL if no window has 
the mouse capture. 


The return value may be temporary, and should not be stored for later use. 


CWhnd::SetCapture, ::GetCapture 
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CWnd::GetCaretPos 


static CPoint GetCaretPosQ); 


Retrieves the client coordinates of the caret’s current position, and copies them to 


a CPoint structure. 


The caret position is given in the client coordinates of the CWnd window. 
CPoint containing the coordinates of the caret’s position. 


::<GetCaretPos 


CWhd::GetCheckedRadioButton 


int GetCheckedRadioButton( int n/DFirstButton, int n/DLastButton ); 


nlDFirstButton 
Specifies the integer identifier of the first radio button in the group. 


nIDLastButton 
Specifies the integer identifier of the last radio button in the group. 


This function retrieves the ID of the currently checked radio button in the 
specified group. 


ID of the checked radio button. 


CWnd::CheckRadioButton 


CWnd::GetClientRect 


void GetClientRect( LPRECT /pRect ) const; 


lpRect 
Points to a RECT structure or a CRect to receive the client coordinates. 
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CWnhd::GetClipboardViewer — 687 


Copies the client coordinates of the CWnd client area into the structure pointed to 
by /pRect. The client coordinates specify the upper-left and lower-right corners of 
the client area. Since client coordinates are relative to the upper-left corners of the 
CWhnd client area, the coordinates of the upper-left corner are (0,0). 


CWnd::GetWindowRect, ::GetClientRect 


CWnd::GetClipboardOwner 


static CWnd* GetClipboardOwner(); 


Retrieves the current owner of the Clipboard. 


The Clipboard can still contain data even if the Clipboard is not currently owned. 


Identifies the CWnd that owns the Clipboard. It is NULL if the Clipboard is not 
owned. | 


The returned pointer may be temporary and should not be stored for later use. 


CWhnd::GetClipboard Viewer, ::GetClipboardOwner 


CWnd::GetClipboardViewer 


static CWnd* GetClipboard Viewer(); 
Retrieves the first window in the Clipboard-viewer chain. 


Identifies the window currently responsible for displaying the Clipboard. It is 
NULL if there is no viewer. 


The returned pointer may be temporary, and should not be stored for later use. 


CWhnd::GetClipboardOwner, ::GetClipboard Viewer 
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Syntax 
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Syntax 
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See Also 


CWnhd::GetCurrentMessage 


Protected: 
static const MSG* GetCurrentMessage(); 


Returns a pointer to the message the window is currently processing. Should only 
be called when in an OnMessage handler. 


CWnd::GetDC 


CDC* GetDCQ; 


Retrieves a pointer to a display context for the client area. The display context can 
be used in subsequent GDI functions to draw in the client area. 


Retrieves a common, class, or private display context depending on the class style 
specified for the CWnd. For common display contexts, GetDC assigns default at- 
tributes to the context each time it 1s retrieved. For class and private contexts, 
GetDC leaves the previously assigned attributes unchanged. 


Unless the display context belongs to a window class, the ReleaseDC member 
function must be called to release the context after painting. Since only five com- 
mon display contexts are available at any given time, failure to release a display 
context can prevent other applications from accessing a display context. 


A display context belonging to the CWnd class is returned by the GetDC member 
function if CS_CLASSDC, CS_QWNDC, or CS_PARENTDC were specified 
as a style in the WNDCLASS structure when the class was registered. 


Identifies the display context for the CWnd client area if the function is success- 
ful. The return value is NULL if the function is unsuccessful. The pointer may be 


temporary, and should not be stored for later use. 


CWnd::ReleaseDC, ::GetDC, CClientDC 
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CWnd::GetDesktopWindow 


static CWnd* GetDesktopWindow(); 


Returns the Windows desktop window. The desktop window covers the entire 
screen and is the area on top of which all icons and other windows are painted. 


Identifies the Windows desktop window. This pointer may be temporary, and 
should not be stored for later use. 


::GetDesktopWindow 


CWnhd::GetDigCtrilD 


int GetDilgCtrlIDQ const; 


Returns the CWnd’s ID value if CWnd 1s a child window. 


Since top-level windows do not have an ID value, the return value of this function 
is invalid if the CWnd is a top-level window. 


The numeric identifier of the CWnd child window if the function is successful. If 
the function fails, the return value is NULL. 


::GetDigCtrlID 


CWnd::GetDigitem 


CWnd* GetDigItem( int n/D ) const; 


nID 
Specifies the integer ID of the item to be retrieved. 
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Retrieves a pointer to the specified control in a dialog box. 


Can be used with any parent-child pair, not just a dialog box, as long as the child 
window has a unique ID (as specified by the n/D parameter in the Create member 
function that created the child window). 


The pointer returned is usually cast to the type of control identified by nID. 


A pointer to the given control. If no control with the integer ID given by the nJD 
parameter exists, the value is NULL. 


The returned pointer may be temporary, and should not be stored. 


CWnd::Create, CWnd::GetWindow, ::GetDigItem 


CWnd::GetDigitemInt 


UINT GetDigItemInt( int 17D, BOOL* [pTrans = NULL, 
BOOL bSigned = TRUE ) const; 


nID 
Specifies the integer identifier of the dialog-box item to be translated. 


lpTrans 
Points to the Boolean variable that is to receive the translated flag. 


bSigned 
Specifies whether the value to be retrieved is signed. 


Translates the text of the specified control in the given dialog box into an integer 
value. 


Retrieves the text of the control identified by nJD. It translates the text by stripping 
any extra spaces at the beginning of the text and converting decimal digits, stop- 
ping the translation when it reaches the end of the text or encounters any non- 
numeric character. 


If bSigned is TRUE, GetDlgItemInt checks for a minus sign (—) at the beginning 
of the text and translates the text into a signed number. Otherwise, it creates an un- 
signed value. 


Sends a WM_GETTEXT message to the control. 
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Specifies the translated value of the dialog-box item text. Since 0 is a valid return 
value, /pTrans must be used to detect errors. If a signed return value is desired, 
cast it as an int type. 


Zero if the translated number is greater than 32,767 (for signed numbers) or 
65,535 (for unsigned). 


When errors occur, such as encountering nonnumeric characters and exceeding the 
given maximum, GetDlgItemInt copies 0 to the location pointed to by /pTrans. If 
there are no errors, [pTrans receives a nonzero value. If IpTrans is NULL, 
GetDlgItemInt does not warn about errors. 


CWnd::GetDigItemText, ::GetDigItemInt 


CWnd::GetDigltemText 


int GetDigItemText( int n/D, LPSTR /pStr, int nMaxCount ) const; 


nID 
Specifies the integer identifier of the dialog-box item whose caption or text is to 
be retrieved. 


lpStr 
Points to the buffer to receive the text. 


nMaxCount 
Specifies the maximum length (in bytes) of the string to be copied to /pStr. If 
the string is longer than nMaxCount, it is truncated. 


Retrieves the caption or text associated with a control in a dialog box. The 
GetDlgItemText member function copies the text to the location pointed to by 
[pStr and returns a count of the number of bytes it copies. 


Specifies the actual number of bytes copied to the buffer. The value is 0 if no text 
is copied. 


CWnd::GetDligItem, CWnd::GetDigItemInt, ::GetDigItemText, 
WM_GETTEXT 
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CWnhd::GetFocus 


static CWnd* GetFocus(); 
Retrieves a pointer to the CWnd that currently has the input focus. 


A pointer to the window that has the current focus, or NULL if there is no focus 
window or an error occurred. 


The pointer may be temporary, and should not be stored for later use. 


CWnd::GetActiveWindow, CWnd::GetCapture, CWnd::SetFocus, 
::GetFocus 


CWnd::GetFont 


CFont* GetFont(); 
Gets the current font. 


A pointer to the current font. 


The pointer may be temporary and should not be stored for later use. 


CWnd::SetFont, WM_GETFONT, CFont 


CWnd::GetLastActivePopup 


CWnd* GetLastActivePopup() const; 


Determines which pop-up window owned by CWnd was most recently active. 
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CWnd::GetNextDigGroupltem 693 


Identifies the most recently active pop-up window. The return value will be the 
CWnd itself if any of the following conditions are met: 


=» CWhnhd itself was most recently active. 
= CWnd does not own any pop-up windows. 


= CWhnd is not a top-level window or is owned by another window. 


The pointer may be temporary, and should not be stored for later use. 


::GetLastActivePopup 


CWnd::GetMenu 


CMenu* GetMenu() const; 


Retrieves a pointer to the CWnd’s menu. This function should not be used for 
child windows because they do not have a menu. 


Identifies the menu. The value is NULL if CWnd has no menu. The return value 
is undefined if CWnd is a child window. 


The returned pointer may be temporary, and should not be stored for later use. 


::;<GetMenu 


CWnd::GetNextDigGroupltem 


CWnd* GetNextDigGroupItem( CWnd* pWndCtl, 
BOOL bPrevious = FALSE ) const; 


pWndCtl 
Identifies the control to be used as the starting point for the search. 


bPrevious 
Specifies how the function is to search the group of controls in the dialog box. 
If this parameter is TRUE, the function searches for the previous control in the 
group. If this parameter is FALSE, the function searches for the next control in 
the group. 


694 CWnd::GetNextDiglabitem 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Searches for the previous (or next) control within a group of controls in a dialog 
box. A group of controls begins with a control that was created with the 
WS_GROUP style and ends with the last control that was not created with 

the WS_GROUP style. 


By default, the GetNextDigGroupItem member function returns a pointer to the 
next control in the group. If pWndCtl identifies the first control in the group and 
bPrevious is TRUE, GetNextDlgGroupItem returns a pointer to the last control 
in the group. 


Pointer to the previous (or next) control in the group. 


The returned pointer may be temporary, and should not be stored for later use. 


CWnd::GetNextDlgTabItem, ::GetNextDlgGroupItem 


CWnd::GetNextDlgTabltem 


CWnd* GetNextDlgTabItem( CWnd* pWndCtl, 
BOOL bPrevious = FALSE ) const; 


pWndCtl 
Identifies the control to be used as the starting point for the search. 

bPrevious 
Specifies how the function is to search the dialog box. If this parameter is 
TRUE, the function searches for the previous control in the dialog box. If this 
parameter is FALSE, the function searches for the next control in the 
dialog box. 


Retrieves a pointer to the first control that was created with the WS_TABSTOP 
style and precedes (or follows) the specified control. 


The return value is the previous (or next) control that has the WS_TABSTOP 
style. 


The returned pointer may be temporary, and should not be stored for later use. 


CWnd::GetNextDlgGrouplItem, ::GetNextDigTabItem 
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CWnd::GetNextWindow 695 


CWnhd::GetNextWindow 
CWnd* GetNextWindow( UINT nFlag = GW_HWNDNEXT ) const; 


nF lag 
Specifies whether the function returns a pointer to the next window or the pre- 
vious window. It can be either of the following values: 


Value Meaning 


GW_HWNDNEXT __ Returns the window that follows the CWnd object 
on the window-manager’s list. 


GW_HWNDPREV __ Returns the previous window on the window- 
manager’s list. 


Searches for the next (or previous) window in the window-manager’s list. The 
window manager’s list contains entries for all top-level windows, their associated 
child windows, and the child windows of any child windows. 


If CWnd is a top-level window, the function searches for the next (or previous) 
top-level window; if CWnd is a child window, the function searches for the next 
(or previous) child window. 


Identifies the next (or the previous) window in the window-manager’s list. 


The returned pointer may be temporary, and should not be stored for later use. 


::;GetNextWindow 
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CWnd::GetParent 


Syntax CWnd* GetParent() const; 

Remarks Retrieves the parent window (if any). 

Return Value Identifies the parent window. The value is NULL if the CWnd has no parent 
window. 


The returned pointer may be temporary, and should not be stored for later use. 


See Also ::GetParent 


CWnhd::GetSafeHwnd 


Syntax HWND GetSafeHwnd() const; 


Return Value Returns m_hWhnd, or NULL if this is NULL. 


CWnd::GetScrollPos 


Syntax int GetScrollPos( int nBar ) const; 
Parameters nBar 
Specifies the scroll bar to examine. The parameter can take one of the following 
values: 
Value Meaning 
SB_CTL Retrieves the position of a scroll-bar control. 


SB_HORZ _ Retrieves the position of the CWnd horizontal scroll bar. 
SB_ VERT Retrieves the position of the CWnd vertical scroll bar. 
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CWnd::GetScrollRange 697 


Retrieves the current position of a scroll box. The current position is a relative 
value that depends on the current scrolling range. For example, if the scrolling 
range 1s 50 to 100 and the thumb is in the middle of the bar, the current position 
is 75. 


Specifies the current position of the scroll box. 


::GetScrollPos 


CWnd::GetScrollRange 


void GetScrollRange( int nBar, LPINT [pMinPos, LPINT [pMaxPos ) const; 


nBar 
Specifies the scroll bar to examine. The parameter can take one of the following 
values: 


Value Meaning 
SB_CTL Retrieves the position of a scroll-bar control. 


SB_HORZ _ Retrieves the position of the CWnd horizontal scroll bar. 
SB_ VERT Retrieves the position of the CWnd vertical scroll bar. 


lpMinPos 
Points to the integer variable that is to receive the minimum position. 


lpMaxPos 
Points to the integer variable that is to receive the maximum position. 


Copies the current minimum and maximum scroll-bar positions for the given 
scroll bar to the locations specified by /pMinPos and lpMaxPos. If CWnd 
does not have standard scroll bars or is not a scroll-bar control, then the 
GetScrollRange member function copies 0 to pMinPos and lpMaxPos. 


The default range for a standard scroll bar is 0 to 100. The default range for a 
scroll-bar control is empty (both values are 0). 


::GetScrollRange 


698 CWhd::GetStyle 


Syntax 
Return Value 


See Also 


Syntax 


Return Value 


Syntax 
Remarks 


Return Value 


See Also 


CWnd::GetStyle 


DWORD GetStyle() const; 
The window’s style. 


::<GetWindowLong, CWnd::CreateEx 


CWnhd::GetSuperWndProcAddr 


protected: virtual FARPROC* GetSuperWndProcAddr(); 


The original WndProc address of a subclassed window. 


CWnd::GetSysModalWindow 


static CWnd* GetSysModalWindow(); 


Returns the system-modal window, if there is one. 


Identifies the system-modal window, if one is present. If no such window is pre- 
sent, the return value is NULL. 


The returned pointer may be temporary, and should not be stored for later use. 


::GetSysModalWindow, CWnd::SetSysModalWindow 
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CWnd::GetSystemMenu __ 699 


CWnd::GetSystemMenu 


CMenu* GetSystemMenu( BOOL bRevert ) const; 


bRevert 
Specifies the action to be taken. 


If bRevert is FALSE, GetSystemMenu returns a handle to a copy of the Con- 
trol menu currently in use. This copy is initially identical to the Control menu, 
but can be modified. 


If bRevert is TRUE, GetSystemMenu resets the Control menu back to the de- 
fault state. The previous, possibly modified, Control menu, if any, 1s destroyed. 
The return value is undefined in this case. 


Allows the application to access the Control menu for copying and modification. 


Any window that does not use GetSystemMenu to make its own copy of the Con- 
trol menu receives the standard Control menu. 


The pointer returned by GetSystemMenu member function can be used with the 
CMenu::AppendMenu, CMenu::InsertMenu, or CMenu::ModifyMenu func- 
tions to change the Control menu. 


The Control menu initially contains items identified with various ID values such 
as SC_CLOSE, SC_MOVE, and SC_SIZE. Menu items on the Control 
generate WM_SYSCOMMAND messages. All predefined Control-menu items 
have ID numbers greater than OxFOOO. If an application adds items to the Control 
menu, it should use ID numbers less than FOOO. 


Windows automatically dims items on the standard Control menu, depending on 
the situation. CWnd can carry out its own checking or dimming by responding to 
the WM_INITMENU messages, which are sent before any menu is displayed. 


Identifies a copy of the Control menu if bRevert is FALSE. If bRevert is TRUE, 
the return value is undefined. 


The returned pointer may be temporary, and should not be stored for later use. 


CMenu::AppendMenu, CMenu::InsertMenu, CMenu::ModifyMenu, 
::GetSystemMenu 
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CWhd::GetTopWindow 


CWnd* GetTopWindow() const; 


Searches for the top-level child window that belongs to CWnd. If CWnd has no 
children, this function returns NULL. 


Identifies the top-level child window in a CWnd linked list of child windows. If 
no child windows exist, the value is NULL. 


The returned pointer may be temporary, and should not be stored for later use. 


::GetTopWindow 


CWhd::GetUpdateRect 


BOOL GetUpdateRect( LPRECT /pRect, BOOL bErase = FALSE ); 


lpRect 
Points to a CRect or RECT structure that is to receive the client coordinates of 
the update enclosing the update region. 


bErase 
Specifies whether the background in the update region is to be erased. 


Retrieves the coordinates of the smallest rectangle that completely encloses the up- 
date region. If CWnd was created with the CS_OWNDC style and the mapping 
mode is not MM_ TEXT, the GetUpdateRect member function gives the rec- 
tangle in logical coordinates. Otherwise, GetUpdateRect gives the rectangle in 
client coordinates. If there is no update region, GetUpdateRect sets the rectangle 
to be empty (sets all coordinates to 0). 


The bErase parameter specifies whether GetUpdateRect should erase the back- 
ground of the update region. If bErase is TRUE and the update region is not 
empty, the background is erased. To erase the background, GetUpdateRect sends 
the WM_ERASEBKGND message. 


The update rectangle retrieved by the BeginPaint member function is identical to 
that retrieved by the GetUpdateRect member function. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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The BeginPaint member function automatically validates the update region, so 
any call to GetUpdateRect made immediately after a call to BeginPaint retrieves 
an empty update region. 


Specifies the status of the update region. The value is TRUE if the update region 
is not empty; otherwise FALSE. 


CWhnd::BeginPaint, ::GetUpdateRect 


CWnd::GetUpdateRgn 


int GetUpdateRgn( CRgn* pRen, BOOL bErase = FALSE ); 


pRgn 
Identifies the update region. 

bErase 
Specifies whether the background will be erased and nonclient areas of child 
windows will be drawn. If the value is FALSE, no drawing is done. 


Retrieves the update region into a region identified by pRgn. The coordinates of 
this region are relative to the upper-left corner (client coordinates). 


The BeginPaint member function automatically validates the update region, so 
any call to GetUpdateRgn made immediately after a call to BeginPaint retrieves 
an empty update region. 


Specifies a short-integer flag that indicates the type of resulting region. The value 
can take any one of the following: 


Value Meaning 

COMPLEXREGION The region has overlapping borders. 
ERROR No region was created. 
NULLREGION The region is empty. 
SIMPLEREGION The region has no overlapping borders. 


CWnd::BeginPaint, ::;GetUpdateRgn 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CWnd::GetWindow 


CWnd* GetWindow( UINT nCmd ) const; 


nCmd 


Specifies the relationship between CWnd and the returned window. It can take 
one of the following values: 


Value 
GW_CHILD 
GW_HWNDFIRST 


GW_HWNDLAST 


GW_HWNDNEXT 


GW_HWNDPREV 


GW_OWNER 


Meaning 
Identifies CWnd’s first child window. 


If CWnd is a child window, returns the first 
sibling window. Otherwise, it returns the first top- 
level window in the list. 


If CWnd is a child window, returns the last sibling 
window. Otherwise, it returns the last top-level 
window in the list. 


Returns the next window on the window- 
manager’s list. 


Returns the previous window on the window- 
manager’s list. 


Identifies CWnd’s owner. 


Searches the window manager’s list for a window. The window-manager’s list 
contains entries for all top-level windows, their associated child windows, and the 
child windows of any child windows. The nCmd parameter specifies the relation- 
ship between CWnd and the returned window. 


Identifies a window. The value is NULL if the function reaches the end of the 
window-manager’s list or if nCmd 1s invalid. 


The returned pointer may be temporary, and should not be stored for later use. 


CWnd::GetDigItem, ::GetWindow 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 
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CWnd::GetWindowDC 


CDC* GetWindowDC(); 


Retrieves the display context for the entire window, including caption bar, menus, 
and scroll bars. A window display context permits painting anywhere in CWnd, 
since the origin of the context is the upper-left corner of CWnd instead of the 
client area. 


Assigns default attributes to the display context each time it retrieves the context. 
Previous attributes are lost. 


Intended to be used for special painting effects within the CWnd nonclient area. 
Painting in nonclient areas of any window is not recommended. 


The GetSystemMetrics Windows function can be used to retrieve the dimensions 
of various parts of the nonclient area, such as the caption bar, menu, and scroll 
bars. 


After painting is complete, the ReleaseDC member function must be called to re- 
lease the display context. Failure to release the display context will seriously affect 
painting requested by applications due to limitations on the number of device con- 
texts that can be open at the same time. 


Identifies the display context for the given window if the function is successful; 
otherwise, the value is NULL. 


The returned pointer may be temporary, and should not be stored for later use. 


::GetSystemMetrics, CWnd::ReleaseDC, ::GetWindowDC, CWnd::GetDC, 
CWindowDC 


CWnd::GetWindowRect 


void GetWindowRect( LPRECT /pRect ) const; 


lpRect 
Points to a CRect or a RECT structure that will receive the screen coordinates 
of the upper-left and lower-right corners. 
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Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Copies the dimensions of the bounding rectangle of the CWnd object to the struc- 
ture pointed to by /pRect. The dimensions are given in screen coordinates, relative 
to the upper-left corner of the display screen. The dimensions of the caption, 
border, and scroll bars, if present, are included. 


CWnd::GetClientRect, CWnd::MoveWindow, CWnd::SetWindowPos, 
::;GetWindowRect 


CWnd::GetWindowText 


int GetWindowText( LPSTR [pString, int nMaxCount ) const; 


[pString 
Points to the buffer that is to receive the copied string of the Window’s title. 
nMaxCount 
Specifies the maximum number of characters to be copied to the buffer. If the 
string is longer than the number of characters specified in nMaxCount, it is trun- 
cated. 


Copies CWnd’s caption title (if it has one) into the buffer pointed to by /pString. 
If the CWnd object is a control, the GetWindowText member function copies the 
text within the control instead of copying the caption. 


Specifies the length of the copied string. It is 0 if CWnd has no caption or if the 
caption is empty. 


CWnd::SetWindowText, CWnd::GetWindowText, WM_GETTEXT 


CWhd::GetWindowTextLength 


int GetWindowTextLength() const; 


Returns the length of the CWnd object caption title. If CWnd is a control, the 
GetWindowTextLength member function returns the length of the text within the 
control instead of the caption. 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 
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Specifies the text length, not including any null-termination character. The value is 
0 if no such text exists. 


::;GetWindowTextLength 


CWnd::HideCaret 


void HideCaret(); 


Hides the caret by removing it from the display screen. Although the caret is no 
longer visible, it can be displayed again by using the ShowCaret member func- 
tion. Hiding the caret does not destroy its current shape. 


Hiding is cumulative. If HideCaret has been called five times in a row, the 
ShowCaret member function must be called five times before the caret will be 
shown. 


CWnd::ShowCaret, ::HideCaret 


CWnhd::HiliteMenultem 
BOOL HiliteMenultem( CMenu* pMenu, UINT n/DHiliteltem, UINT nHilite ); 


pMenu 
Identifies the top-level menu that contains the item to be highlighted. 


nlDHilitelItem 
Specifies the integer identifier of the menu item or the offset of the menu item 
in the menu, depending on the value of the nHilite parameter. 
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Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


nHilite 
Specifies whether the menu item is highlighted or the highlight is removed. It 
can be a combination of MF_ HILITE or MF_UNHILITE with 
MF_BYCOMMAND or MF_BYPOSITION. The values can be combined 
using the bitwise OR operator. These values have the following meanings: 


Value Meaning 


MF_BYCOMMAND Interprets n/DHiliteItem as the menu-item ID (the 
default interpretation). 


MF_BYPOSITION Interprets n/DHiliteltem as an offset. 


MF_HILITE Highlights the item. If this value is not given, 
highlighting is removed from the item. 
MF_UNHILITE Removes highlighting from the item. 


Highlights or removes the highlighting from a top-level (menu-bar) menu item. 


Specifies whether the menu item was highlighted. TRUE if the item was 
highlighted; otherwise FALSE. 


CMenu::ModifyMenu, ::HiliteMenultem 


CWhd::Invalidate 


void Invalidate( BOOL bErase = FALSE ); 


bErase 
Specifies whether the background within the update region is to be erased. 


Invalidates the entire client area of CWnd. The client area is marked for painting 
when the next WM_PAINT message occurs. The region can also be validated 
before a WM_PAINT message occurs by using the ValidateRect or 
ValidateRgn member function. 


The bErase parameter specifies whether the background within the update area is 
to be erased when the update region is processed. If bErase is TRUE, the back- 
ground is erased when the BeginPaint member function is called; if bErase is 


FALSE, the background remains unchanged. If bErase is TRUE for any part of 


the update region, the background in the entire region is erased, not just in the 
given part. 


See Also 


syntax 


Parameters 


Remarks 


See Also 
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Windows sends WM_ PAINT whenever the CWnd update region is not empty 
and there are no other messages in the application queue for that window. 


CWnd::BeginPaint, CWnd:: ValidateRect, CWnd:: ValidateRgn, 
::InvalidateRect 


CWnd::InvalidateRect 


void InvalidateRect( LPRECT /pRect, BOOL bErase = FALSE ); 


[pRect 
Points to a CRect or a RECT structure that contains the rectangle (in client 
coordinates) to be added to the update region. If JpRect is NULL, the entire 
client area is added to the region. 


bErase 
Specifies whether the background within the update region is to be erased. 


Invalidates the client area within the given rectangle by adding that rectangle to 
the CWnd update region. The invalidated rectangle, along with all other areas in 
the update region, is marked for painting when the next WM_ PAINT message is 
sent. The invalidated areas accumulate in the update region until the region 1s 
processed when the next WM_ PAINT call occurs, or the region is validated by 
using the ValidateRect or ValidateRgn member function. 


The bErase parameter specifies whether the background within the update area is 
to be erased when the update region is processed. If bErase is TRUE, the back- 
ground is erased when the BeginPaint member function is called; if bErase 1s 
FALSE, the background remains unchanged. If bErase is TRUE for any part of 
the update region, the background in the entire region is erased, not just in the 
given part. 


Windows sends WM_ PAINT whenever the CWnd update region is not empty 
and there are no other messages in the application queue for that window. 


CWhnd::BeginPaint, CWnd:: ValidateRect, CWnd:: ValidateRgn, 
::InvalidateRect 
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Syntax 


Parameters 


Remarks 


See Also 


CWnd::InvalidateRgn 


void InvalidateRgen( CRgn* pRen, BOOL bErase = FALSE ); 


pRgn | 
Identifies the region to be added to the update region. The region is assumed to 
have client coordinates. 


_ bErase 


Specifies whether the background within the update region is to be erased. 


Invalidates the client area within the given region by adding it to the current up- 
date region of CWnd. The invalidated region, along with all other areas in the up- 
date region, is marked for painting when the WM_ PAINT message is next sent. 
The invalidated areas accumulate in the update region until the region is processed 
when WM_PAINT is next sent, or the region is validated by using the 
ValidateRect or ValidateRgn member function. 


The bErase parameter specifies whether the background within the update area is 
to be erased when the update region is processed. If bErase is TRUE, the back- 
ground is erased when the BeginPaint member function is called; if bErase is 
FALSE, the background remains unchanged. If bErase is TRUE for any part of 
the update region, the background in the entire region is erased, not just in the 
given part. 


Windows sends WM_ PAINT whenever the CWnd update region is not empty 
and there are no other messages in the application queue for that window. 


The given region must have been previously created by using one of the region 
functions. 


CWhnd::BeginPaint, CWnd:: ValidateRect, CWnd:: ValidateRgn, 
::InvalidateRgn 
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CWnd::lsChild 


syntax BOOL IsChild( CWnd* pWaud ) const; 


Parameters pWnd 
Identifies the window to be checked. 


Remarks Indicates whether the window specified by pWnd is a child window or other direct 
descendant of CWnd. A child window is the direct descendant of CWnd if the 
CWhnd object is in the chain of parent windows that leads from the original pop- 
up window to the child window. 


Return Value Specifies the outcome of the function. The value is TRUE if the window iden- 
tified by pWnd is a child window of CWnd; otherwise FALSE. 


See Also ::IsChild 


CWnd::IsDigButtonChecked 


Syntax UINT IsDlgButtonChecked( int n/DButton ) const; 


Parameters nlDButton 
Specifies the integer identifier of the button control. 


Remarks If the CWnd object is a button control, the IsDlgButtonChecked member func- 
tion determines whether it has a check mark next to it. If it is a three-state button 
control, it determines if it 1s dimmed, checked, or neither. 


Return Value Nonzero if the given control is checked, and 0 if it is not checked. For three-state 
buttons, the return value is 2 if the button 1s dimmed, 1| if the button is checked, 


and 0 if it is unchecked: 


See Also ::IsDigButtonChecked 
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Syntax 
Remarks 


Return Value 


See Also 


Syntax 
Remarks 


Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


CWnd::Islconic 
BOOL IsIconic() const; 
Specifies whether CWnd is minimized (iconic). 


Specifies whether the CWnd object is minimized. It is TRUE if CWnd is min- 
imized; otherwise FALSE. 


::IsIconic 


CWnd::lsWindowEnabled 


BOOL IsWindowEnabled() const; 
Specifies whether CWnd is enabled for mouse and keyboard input. 


Specifies whether CWnd is enabled. The value is TRUE if it is enabled; other- 
wise FALSE. 


::IsWindowEnabled 


CWnd::lsWindowVisible 
BOOL IsWindowVisible() const; 


Returns TRUE any time an application has made CWnd visible by using the 


ShowWindow member function (even if CWnd is completely covered by another 


child or pop-up window, the return value is TRUE). 


Specifies whether a given window exists on the screen. It is TRUE if it exists on 
the screen; otherwise FALSE. 


CWnd::ShowWindow, ::IsWindowVisible 


Syntax 
Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 
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CWnd::lsZoomed 


BOOL IsZoomed() const; 
Determines whether CWnd has been maximized. 


Specifies whether CWnd is maximized. The value is TRUE if it is maximized; 
otherwise FALSE. 


::IsZoomed 


CWnd::KillTimer 


BOOL KillTimer( int n/DEvent ); 


nlDEvent 
The value of the timer event passed to SetTimer. 


Kills the timer event identified by n/DEvent from the earlier call to SetTimer. 
Any pending WM_ TIMER messages associated with the timer are removed from 
the message queue. 


Specifies the outcome of the function. The value is TRUE if the event was killed. 
It is FALSE if the KillTimer member function could not find the specified timer 


event. 


CwWhnd::SetTimer, ::KillTimer 


CWnd::MessageBox 


int MessageBox( const char FAR* /pTJext, const char FAR* [pCaption = NULL, 
UINT nType = MB_ OK ); 


lpText 
Points to a CString or null-terminated string containing the message to be dis- 
played. 
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lpCaption 


Points to a CString or null-terminated string to be used for the message-box 
caption. If IpCaption is NULL, the default caption “Error” is used. 


nlype 


Specifies the contents of the message box. It can be a combination of the follow- 


ing values: 


Value 


MB_ABORTRETRYIGNORE 


MB_APPLMODAL 


MB_DEFBUTTON1 


MB_DEFBUTTON2 
MB_DEFBUTTON3 
MB_ICONEXCLAMATION 


MB_ICONINFORMATION 
MB_ICONQUESTION 
MB_ICONSTOP 

MB_OK 

MB_ OKCANCEL 


MB_ RETRY CANCEL 


Meaning 


Message box contains three push 
buttons: Abort, Retry, and Ignore. 


The user must respond to the message 
box before continuing work in the 
CWhnd. However, the user can move to 
the windows of other applications and 
work in those windows. 
MB_APPLMODAL is the default if 
MB_SYSTEMMODAL is not 
specified. 


First button 1s the default. Note that the 


first button is always the default unless 
MB_DEFBUTTON2 or 
MB_DEFBUTTONS is specified. 


Second button is the default. 
Third button is the default. 


An exclamation-point icon appears in 
the message box. 


66599 


An icon consisting of a lowercase “1” in 
a circle appears in the message box. 


A question-mark icon appears in the 
message box. 


A stop-sign icon appears in the message 
box. 


Message box contains one push button: 
OK. 


Message box contains two push buttons: 
OK and Cancel. 


Message box contains two push buttons: 
Retry and Cancel. 


Remarks 


Return Value 
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Value Meaning 


MB_SYSTEMMODAL All applications are suspended until the 
user responds to the message box. 
Unless the application specifies 
MB_ICONSTOP, the message box 
does not become modal until after it is 
created; consequently, the parent 
window and other windows continue to 
receive messages resulting from its 
activation. System-modal message 
boxes are used to notify the user of 
serious, potentially damaging errors that 
require immediate attention (for 
example, running out of memory). 


MB_YESNO Message box contains two push buttons: 
Yes and No. 
MB_YESNOCANCEL Message box contains three push 


buttons: Yes, No, and Cancel. 


Creates and displays a window that contains an application-supplied message and 
caption, plus a combination of the predefined icons and push buttons described in 
the preceding list. 


When a system-modal message box is created to indicate that the system is low on 
memory, do not take the strings passed as /pText and lpCaption from a resource 
file, since an attempt to load the resource may fail. 


When an application calls the MessageBox member function and specifies the 
MB_ICONSTOP and MB_SYSTEMMODAL flags for nType, Windows will 
display the resulting message box regardless of available memory. When these 
flags are specified, Windows limits the length of the message-box text to one line. 


Specifies the outcome of the function. It is 0 if there is not enough memory to cre- 
ate the message box. Otherwise, it is one of the following menu-item values re- 
turned by the message box: 


Value Meaning 

IDABORT Abort button pressed 
IDCANCEL Cancel button pressed 
IDIGNORE Ignore button pressed 


IDNO No button pressed 
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See Also 


Syntax 


Parameters 


Remarks 


Value Meaning 

IDOK OK button pressed 
IDRETRY Retry button pressed 
IDYES Yes button pressed 


If a message box has a Cancel button, the IDCANCEL value will be returned if 
either the Esc key or the Cancel button is pressed. If the message box has no 
Cancel button, pressing the ESC key has no effect. 


::MessageBox 


CWnd::MoveWindow 


void Move Window( int x, int y, int nWidth, int nHeight, 
BOOL bRepaint = TRUE ); 


void MoveWindow( LPRECT /pRect, BOOL bRepaint = TRUE ); 


x 
Specifies the new position of the left side of the window. 


Specifies the new position of the top of the window. 


nWidth 
Specifies the new width of the window. 


nHeight 
Specifies the new height of the window. 


bRepaint 
Specifies whether the window is to be repainted. If this parameter is TRUE, the 
window is repainted. This is set by default. 


lpRect 
The CRect or RECT structure specifying the new size and position. 


Changes the position and dimensions. 


For a top-level CWnd object, the x and y parameters are relative to the upper-left 
corner of the screen. For a child CWnd object, they are relative to the upper-left 
corner of the parent window’s client area. 


See Also 


syntax 


Parameters 


Remarks 


See Also 


CWnd::OnActivate 715 


The MoveWindow function sends WM_GETMINMAXINFO. This gives 
CWhnd the opportunity to modify the default values for the largest and smallest 
possible windows. If the parameters to the MoveWindow member function 
exceed these values, the values will be replaced by the minimum or maximum 
values specified in the WM_GETMINMAXINFO message. 


CWnd::SetWindowPos, ::MoveWindow 


CWnd::0nActivate 


afx_msg void OnActivate( UINT nState, CWnd* pWndOther, 
BOOL bMinimized ); 


nState 
Indicates the minimized state of the window being activated or deactivated. A 
nonzero value indicates that the CWnd object is minimized. 


pWndOther 
Pointer to the CWnd being activated or deactivated. The pointer can be NULL, 
and it may be temporary. 

bMinimized 
If TRUE, the CWnd is being activated; otherwise deactivated. 


Called when a CWnd object is being activated or deactivated. First, the main win- 
dow being deactivated has OnActivate called, and then the main window being ac- 
tivated has OnActivate called. 


If the CWnd object is activated with a mouse click, it will also receive an 
OnMouseActivate member function call. 


This message-handler member function calls the Default member function. Over- 
ride this member function in your derived class to handle the WM_ ACTIVATE 
message. 


WM_MOUSEACTIVATE, WM_NCACTIVATE, CWnd::Default, 
WM_ACTIVATE 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CWnd::O0nActivateApp 


afx_msg void OnActivateApp( BOOL bActive, HANDLE hTask ); 


bActive 
Specifies whether the CWnd is being activated or deactivated. TRUE means 
the CWnd is being activated. FALSE means the CWnd is being deactivated. 


hTask 
Specifies a task handle. If bActive is TRUE, the handle identifies the task that 
owns the CWnd being deactivated. If bActive is FALSE, the handle identifies 
the task that owns the CWnd being activated. 


Called when CWnd is about to be activated and CWnd belongs to a different task 
than the currently active window. OnActivateApp is called for all top-level win- 
dows of the task being activated, and for all top-level windows of the task being 
deactivated. 


This message-handler member function calls the Default member function. Over- 
ride this member function in your derived class to handle the 
WM_ACTIVATEAPP message. 


CWnd::Default, WM_ACTIVATEAPP 


CWnd::0nAskCbFormatName 


afx_msg void OnAskCbFormatName( UINT nMaxCount, LPSTR IpString ); 


nMaxCount 
Specifies the maximum number of bytes to copy. 
[pString 
Points to the buffer where the copy of the format name is to be stored. 


Called when the Clipboard contains a data handle for the 
CF_OWNERDISPLAY format (that is, when the Clipboard owner will display 
the Clipboard contents) and the Clipboard owner should provide a name for 

its format. 


Override this member function and copy the name of the 
CF_OWNERDISPLAY format into the specified buffer, not BeRecenine 
the maximum number of bytes specified. 


See Also 


Syntax 


Remarks 


See Also 


syntax 


Parameters 


Remarks 


CWnd::OnChangeCbChain = 717 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ASKCBFORMATNAME message. 


CWnd::Default, WM_ ASKCBFORMAINAME 


CWnd::O0nCancelMode 


afx_msg void OnCancelMode(); 


If the CWnd object has the focus, its OnCancelMode member function is called 


when a dialog box or message box is displayed. This gives the CWnd the opportu- 


nity to cancel modes such as mouse capture. 


Calls the Default member function, which responds by calling the 
ReleaseCapture Windows function. The Default member function does not can- 
cel any other modes. 


Override this member function in your derived class to handle the 
WM_CANCELMODE message. 


CWnd::Default, :: ReleaseCapture, WM_CANCELMODE 


CWnd::OnChangeCbChain 


afx_msg void OnChangeCbChain( HWND hWndRemove, HWND hWndAfter ); 


hWndRemove 
Specifies the window handle that is being removed from the Clipboard-viewer 
chain. 


hWndAfter 
Specifies the window handle that follows the window being removed from the 
Clipboard-viewer chain. 


Called for each window in the Clipboard-viewer chain to notify it that a window is 


being removed from the chain. 
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See Also 


Syntax 


Parameters 


Each CWnd object that receives an OnChangeCbChain call should use the 
SendMessage Windows function to send the WM_CHANGECBCHAIN mes- 
sage to the next window in the Clipboard-viewer chain (the handle returned by 
SetClipboard Viewer). If :WndRemove is the next window in the chain, the win- 
dow specified by hWndAfter becomes the next window, and Clipboard messages 
are passed on to it. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_CHANGECBCHAIN message. 


CWnd::ChangeClipboardChain, ::SendMessage, CWnd::Default 


CWnd::OnChar 


afx_ msg void OnChar( UINT nChar, UINT nRepCnt, UINT nFlags ); 


nChar 

Contains the value of the key. 
nRepCnt 

Contains the repeat count. 
nFlags 


Contains the scan code, key-transition code, previous key state, and context 
code, as shown in the following list: 


Value Description 

O-7 Scan code (OEM-dependent value). 

8 Extended key, such as a function key or a key on the numeric 
keypad (1 if it is an extended key). 

11-12 Used internally by Windows. 

13 Context code (1 if the ALT key is held down while the key is 
pressed, 0 otherwise). 

14 Previous key state (1 if the key 1s down before the call, 0 if the 
key is up). 

15 Transition state (1 if the key is being released, 0 if the key is 


being pressed). 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CWnd::OnCharToltem 719 


Called before the OnKeyUp member function and after the OnKeyDown mem- 
ber function are called. OnChar contains the value of the keyboard key being 
pressed or released. 


Since there is not necessarily a one-to-one correspondence between keys pressed 
and OnChar calls generated, the information in nFlags is generally not useful to 
applications. The information in nFlags applies only to the most recent call to the 
OnKeyUp member function or the OnKeyDown member function that precedes 
the call to OnChar. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
and the right CONTROL keys on the main section of the keyboard; the INS, DEL, 
HOME, END, PAGE UP, PAGE DOWN, and ARROW keys in the clusters to the left of the 
numeric keypad; and the slash (/) and ENTER keys in the numeric keypad. Some 
other keyboards may support the extended-key bit in nFlags. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the WM_CHAR 
message. 


CWnd::Default, WM_CHAR, WM_KEYDOWN, WM_KEYUP 


CWnd::OnCharToltem 


afx_ msg int OnCharTolItem( UINT nChar, CWnd* pListBox, UINT nindex ); 


nChar 
Specifies the value of the key pressed by the user. 


pListBox 
Specifies a pointer to the list box. It may be temporary. 


nIndex 
Specifies the current caret position. 


A list box with the LBS_WANTKEYBOARDINPUT style sends its owner a 
WM_CHARTOITEM message in response to a WM_CHAR message. 
WM_CHARTOITEM is handled by default by OnCharToltem. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_CHARTOITEM message. 
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Return Value 


See Also 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


Specifies the action that the application performed in response to the call. A return 
value of —2 indicates that the application handled all aspects of selecting the item 
and wants no further action by the list box. A return value of —1 indicates that the 
list box will perform the default action in response to the keystroke. A return value 
of O or greater specifies the index of an item in the list box and indicates that the 
list box will perform the default action for the keystroke on the given item. 


CWnd::Default, WM_CHAR, WM_ CHARTOITEM 


CWnhd::OnChildActivate 


afx_msg void OnChildActivate(; 


If the CWnd object is a child window, OnChild Activate is called whenever the 
size or position of the window changes. 


This message-handler member function calls the Default member function. 


Override this member function in your derived class to handle the 
WM_CHILDACTIVATE message. 


CWnd::SetWindowPos, CWnd::OnClose, WM_CHILDACTIVATE, 
CWnd:: Default 


CWnd::O0nClose 


afx_msg void OnCloseQ); 


Called as a signal that the CWnd or an application is to terminate. An application 
can prompt the user for confirmation and destroy the CWnd object by calling the 
DestroyWindow member function only if the user confirms the choice. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the WM_CLOSE 
message. 


CWnd::Destroy Window, ::PostQuitMessage, WM_CLOSE, CWnd::Default 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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CWnd::0nCommand 


virtual BOOL OnCommand( UINT wParam, LONG [Param ); 


wParam 
Identifies the menu item or control. 


[Param 
Specifies additional information. If the message is from a menu, the low-order 
word and the high-order word are both 0. If the message is from an accelerator, 
the low-order word is 0 and the high-order word is 1. If the message is from a 
control, the low-order word is the handle of the window sending the message 
and the high-order word is the notification code. 


Called when the user selects an item from a CWnd menu, when a child control 
sends a notification message to CWnd, or when an access keystroke is translated. 


Access keystrokes that are defined to select items from the Control menu are trans- 
lated to WM_SYSCOMMAND messages. 


If an access keystroke that corresponds to a menu item occurs when the CWnd is 
minimized, OnCommand is not called. However, if an access keystroke that does 
not match any of the items on the CWnd menu or on the Control menu occurs, 
OnCommand is called, even if CWnd is minimized. 


OnCommand processes the message map for control notification and 
ON_COMMAND entries, and calls the appropriate member function. 


Override this member function in your derived class to handle the 


WM_COMMAND message. An override will not process the message map 
unless the base class OnCommand is called. 


An application returns TRUE if it processes this message; otherwise FALSE. 


WM_SYSCOMMAND, WM_COMMAND 
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CWnd::OnCompacting 


afx_msg void OnCompacting( UINT nCpuTime ); 


nCpulime 
Specifies the ratio of CPU time currently spent by Windows compacting 
memory. For example, 8000h represents 50 percent of CPU time. 


Called for all top-level windows when Windows detects that more than 12.5 per- 
cent of system time over a 30- to 60-second interval is being spent compacting 
memory. This indicates that system memory is low. 


When a CWnd object receives this call, it should free as much memory as 
possible, taking into account the current level of activity of the application and the 
total number of applications running in Windows. The application can call the 
GetNumTasks Windows function to determine how many applications are — 
running. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_COMPACTING message. 


::;GetNumTasks, CWnd::Default, WM_COMPACTING 


CWnd::OnCompareltem 


afx_ msg int OnComparelItem( LPCOMPAREITEMSTRUCT 
lpCompareltemStruct ); 


lpCompareltemStruct 
Contains a long pointer to a COMPAREITEMSTRUCT data structure that 
contains the identifiers and application-supplied data for two items in the 
combo or list box. 


Override this member function in your derived class to handle the 
WM_COMPAREITEM message. 


Use the overridden member function to specify the relative position of a new item 


- in asorted owner-draw combo or list box. 


Members 


CWnd::0nCompareltem 723 


If a combo or list box is created with the CBS_SORT or LBS_SORT style, 
Windows sends the combo-box or list-box owner a WM_COMPAREITEM 
message whenever the application adds a new item. 


The [pCompareltemStruct parameter is a long pointer to a 
COMPAREITEMSTRUCT data structure that contains the identifiers and appli- 
cation-supplied data for two items in the combo or list box. OnComparelItem 
should return a value indicating which of the items should appear before the other. 
Typically, Windows makes this call several times until it determines the exact 
position for the new item. 


A COMPAREITEMSTRUCT data structure has this form: 


typedef struct tagCOMPAREITEMSTRUCT { 
WORD CtlType; 
WORD CELID: 
HWND hwndItem; 
WORD itemID1; 
DWORD itemDatal; 
WORD itemID2; 
DWORD itemData2z; 
} COMPAREITEMSTRUCT; 


CtlType 
ODT_LISTBOX (which specifies an owner-draw list box) or 
ODT_COMBOBOXxX (which specifies an owner-draw combo box). 


CtlID 
The control ID for the list box or combo box. 


hwndItem 
The window handle of the control. 


itemID1 


_ The index of the first item in the list box or combo box being compared. 


itemDatal 
Application-supplied data for the first item being compared. This value was 
passed in the call that added the item to the combo or list box. 


itemID2 
Index of the second item in the list box or combo box being compared. 


itemData2 | 
Application-supplied data for the second item being compared. This value was 
passed in the call that added the item to the combo or list box. 


This message-handler member function calls the Default member function. 
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Indicates the relative position of the two items. It may be any of the following 
values: 


Value Meaning 
—] Item 1 sorts before item 2. 
0) Item 1 and item 2 sort the same. 


Item 1 sorts after item 2. 


COMPAREITEMSTRUCT, WM_COMPAREITEM, CWnd::Default 


CWnd::OnCreate 


afx_msg int OnCreate( LPCREATESTRUCT [pCreateStruct ); 


lp Create Struct 
Points toa CREATESTRUCT structure containing information about the 
CWhnhd object being created. 


Called when an application requests that the CWnd object be created by calling 
the Create or CreateEx member function. The new CWnd object receives this 
call after the CWnd object is created but before it becomes visible. OnCreate is 
called before the Create or CreateEx member function returns. 


Override this member function to perform any needed initialization of a derived 
class. 


The CREATESTRUCT structure contains copies of the parameters used to create 
the window. 


Members 
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A CREATESTRUCT structure has the following form: 


typedef struct tagCREATESTRUCT { 
LPSTR |IpCreateParams; 
HANDLE hInstance; 
HANDLE hMenu; 
HWND hwndParent; 


int Cy; 
THE Cx: 
int y; 
int x: 


LONG style; 

LPS lpszName; 

LEPSTR IpszClass; 

DWORD dwExStyle; 
} CREATESTRUCT; 


IpCreateParams 
Points to data to be used for creating the window. 


hInstance 
Identifies the module-instance handle of the module that owns the new window. 


hMenu 
Identifies the menu to be used by the new window. If a child window, contains 
the integer ID. 


hwndParent 
Identifies the window that owns the new window. This member is NULL if the 
new window is a top-level window. 


cy 

Specifies the height of the new window. 
cx 

Specifies the width of the new window. 


Specifies the y-coordinate of the upper-left corner of the new window. Coordi- 
nates are relative to the parent window if the new window is a child window. 
Otherwise, the coordinates are relative to the screen origin. 


Specifies the x-coordinate of the upper-left corner of the new window. Coordi- 
nates are relative to the parent window if the new window is a child window. 
Otherwise, the coordinates are relative to the screen origin. 
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style 
Specifies the new window’s style. 


IpszName 
Points to a null-terminated string that specifies the new window’s name. 


IpszClass 
Points to a null-terminated string that specifies the new window’s Windows 
class name (a WNDCLASS struct). 

dwExStyle 
Specifies the extended style for the new window. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ CREATE message. 


OnCreate must return 0 to continue the creation of the CWnd object. If the appli- 
cation returns —1, the CWnd will be destroyed. 


CWnd::CreateEx, CWnd::OnNcCreate, WM_CREATE, CWnd::Default, 
CWnd::FromHandle 


CWnd::OnCtiColor 


afx_msg HBRUSH OnCtiColor( CDC* pDC, CWnd* pWhd, 
UINT nCtlColor ); 


pDC 
Contains a pointer to the display context for the child window. May be tem- 
porary. 


pWnd 
Contains a pointer to the child CWnd. May be temporary. 
nCtlColor 
Contains one of the following values, specifying the type of control: 
Value Meaning 
CTLCOLOR_BTN Button control 
CTLCOLOR_DLG Dialog box 


CTLCOLOR_EDIT Edit control 


Remarks 


Return Value 


See Also 
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Value Meaning 
CTLCOLOR_LISTBOX List box control 
CTLCOLOR_MSGBOX Message box 
CTLCOLOR_SCROLLBAR _ Scroll-bar control 
CTLCOLOR_STATIC Static control 


Called when a child system-defined control class or a message box is about to be 
drawn. The following controls call OnCtlColor: 


Combo boxes Buttons 
Edit controls Static controls 
List boxes Scroll bars 


To change the background color of a single-line edit control, you must set the 
brush handle in both the CTLCOLOR_ EDIT and CTLCOLOR_MSGBOX 
message codes, as well as calling the SetBkColor function in response to the 
CTLCOLOR_ EDIT code. 


The return value from the function has no effect on a button with the 
BS_ PUSHBUTTON or BS_DEFPUSHBUTTON style. 


This message-handler member function calls the Default member 


function. Override this member function in your derived class to handle the 
WM_CTLCOLOR message. 


OnCtlColor must return a handle to the brush that is to be used for painting the 
control background, or it must return NULL. 


CDC::SetBkColor, WM_CTLCOLOR, CWnd::Default 


CWnd::OnDeadChar 


afx_msg void OnDeadChar( UINT nChar, UINT nRepCnt, UINT nFlags ); 


nChar 
Specifies the dead-key character value. 


nRepCnt 
Specifies the repeat count. 
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CWnd::OnDeadChar 


nFlags 
Specifies the scan code, key-transition code, previous key state, and context 
code, as shown in the following list: 


Value Description 

O-7 Scan code (OEM-dependent value). Low byte of high-order 
word. 

8 Extended key, such as a function key or a key on the numeric 
keypad (1 if it is an extended key, 0 otherwise). 

9-10 Not used. 

11-12 Used internally by Windows. 

13 Context code (1 if the ALT key is held down while the Key is 
pressed, O otherwise). 

14 Previous key state (1 if the key is down before the call, 0 if the 
key is up). 

15 Transition state (1 if the key is being released, 0 if the Key is 
being pressed). 


Called when the OnKeyUp member function and the OnKeyDown member func- 
tions are called. This member function can be used to specify the character value 
of a dead key. A dead key is a key, such as the umlaut (double-dot) character, that 
is combined with other characters to form a composite character. For example, the 
umlaut-O character consists of the dead key, umlaut, and the o key. 


An application typically uses OnDeadChar to give the user feedback about each 
key pressed. For example, an application can display the accent in the current char- 
acter position without moving the caret. 


Since there is not necessarily a one-to-one correspondence between keys pressed 
and OnDeadChar calls, the information in nFlags is generally not useful to appli- 
cations. The information in nFlags applies only to the most recent call to the 
OnKeyUp member function or the OnKeyDown member function that precedes 
the OnDeadChar call. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
and the right CONTROL keys on the main section of the keyboard; the INS, DEL, 
HOME, END, PAGE UP, PAGE DOWN, and ARROW keys in the clusters to the left of the 
numeric keypad; and the slash (/) and ENTER Keys in the numeric keypad. Some 
other keyboards may support the extended-key bit in nFlags. 


See Also 
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Remarks 


Members 
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This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_DEADCHAR message. 


CWhnd::Default, WM_DEADCHAR 


CWnd::OnDeleteltem 


afx_msg void OnDeleteItem( LPDELETEITEMSTRUCT /pDeleteltemStruct ); 


[pDeleteltemStruct 
Specifies a long pointer to a DELETEITEMSTRUCT data structure that con- 
tains information about the deleted list box item. 


Called to inform the owner of an owner-draw list box or combo box that the 
list box or combo box is destroyed or that items are removed by 
CComboBox::DeleteString, CListBox::DeleteString, 
CComboBox::ResetContent, or CListBox::ResetContent. 


A DELETEITEMSTRUCT data structure has this form: 


typedef struct tagDELETEITEMSTRUCT { 
WORD CtlType 
WORD CtlID; 
WORD itemID; 
HWND hwndItem; 
DWORD itemData; 
} DELETEITEMSTRUCT; 


CtlType 
Contains ODT_LISTBOX (which specifies an owner-draw list box) or 
ODT_COMBOBOX (which specifies an owner-draw combo box). 


CtlID 
Contains the control ID for the list box or combo box. 


itemID 
Contains the index of the item in the list box or combo box being removed. 


hwndItem 
Contains the window handle of the control. 
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itemData 
Contains the value passed to the control by CComboBox::AddString, 
CComboBox::InsertString, CListBox::AddString or 
CListBox::InsertString. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_DELETEITEM message. 


CComboBox::DeleteString, CListBox::DeleteString, 
CComboBox::ResetContent, CListBox::ResetContent, CWnd::Default, 
WM_DELETEITEM 


CWnd::O0nDestroy 


afx_msg void OnDestroy(); 


Called to inform the CWnd that it is being destroyed. OnDestroy is called after 
the CWnd object is removed from the screen. 


OnDestroy is called first for the CWnd being destroyed, then for the child win- 
dows of CWnd as they are destroyed. It can be assumed that all child windows 
still exist while OnDestroy runs. 


If the CWnd is the main window (CWinApp’s m_pMainWnd) then OnDestroy 
calls PostQuitMessage. 


If the CWnd object being destroyed is part of the Clipboard-viewer chain (set by 
calling the SetClipboard Viewer member function), the CWnd must remove itself 
from the Clipboard-viewer chain by calling the ChangeClipboardChain member 
function before returning from the OnDestroy function. 


CWnd::ChangeClipboardChain, CWnd::Destroy Window, 
::PostQuitMessage, CWnd::SetClipboard Viewer, WM_DESTROY 
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See Also 


Syntax 
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CWnd::O0nDestroyClipboard 


afx_msg void OnDestroyClipboard(); 


Called for the Clipboard owner when the Clipboard is emptied through a call to 
the EmptyClipboard Windows function. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ DESTROY CLIPBOARD message. 


::EmptyClipboard, CWnd::Default, WM_DESTROY CLIPBOARD 


CWnhd::0nDevModeChange 


afx_msg void OnDevModeChange( LPSTR /pDeviceName ); 


lpDeviceName 
Points to the device name specified in the Windows initialization file, WIN.INI. 


Called for all top-level CWnds when the user changes device-mode settings. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_DEVMODECHANGE message. 


CWnd::Default, WM_DEVMODECHANGE 


CWnd::O0nDrawClipboard 


afx_msg void OnDrawClipboard(); 


Called for each window in the Clipboard-viewer chain when the contents of the 
Clipboard change. Only applications that have joined the Clipboard-viewer chain 
by calling the SetClipboard Viewer member function need to respond to this call. 
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Each window that receives an OnDrawClipboard call should call the 
SendMessage Windows function to pass a WM_DRAWCLIPBOARD message 
on to the next window in the Clipboard-viewer chain. The handle of the next win- 
dow is returned by the SetClipboard Viewer member function; it may be mod- 
ified in response to an OnChangeCbChain member function call. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_DRAWCLIPBOARD message. 


::SendMessage, CWnd::SetClipboard Viewer, WM_CHANGECBCHAIN, 
CWhnd:: Default 


CWnd::OnDrawitem 


afx_msg void OnDrawlItem( LPDRAWITEMSTRUCT [pDrawltemStruct ); 


lpDrawltemStruct 
Specifies a long pointer toa DRAWITEMSTRUCT data structure that con- 
tains information about the item to be drawn and the type of drawing required. 


Called for the owner of an owner-draw button control, combo-box control, list-box 
control, or menu when a visual aspect of the control or menu has changed. 


The itemAction member of the DRAWITEMSTRUCT structure defines the 
drawing operation that is to be performed. The data in this member allows the 
owner of the control to determine what drawing action is required. 


Before returning from processing this message, an application should ensure that 
the device context identified by the hDC member of the DRAWITEMSTRUCT 
structure 1s restored to the default state. 


CWnd::0nDrawitem 


A DRAWITEMSTRUCT structure has this form: 


typedef struct tagDRAWITEMSTRUCT { 


WORD 
WORD 
WORD 
WORD 
WORD 
HWND 
HDC 
RECT 
DWORD 


CtiType; 
CeLED: 
itemID; 
jtemAction; 
itemState; 
hwndI tem; 
hDC; 
rcItem; 
itemData; 


} DRAWITEMSTRUCT; 
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Members CtlType 

Is the control type. The values for control types are as follows: 
Value Meaning 
ODT_BUTTON Owner-draw button. 
ODT_COMBOBOX Owner-draw combo box. 
ODT_LISTBOX Owner-draw list box. 
ODT_MENU Owner-draw menu. 

CtliD 
The control ID for a combo box, list box, or button. This member is not used 
for a menu. 

itemID 


The menu-item ID for a menu or the index of the item in a list box or combo 
box. For an empty list box or combo box, this member can be —1. This allows 


the application to draw only the focus rectangle at the coordinates specified by 


the recItem member even though there are no items in the control. This indi- 


cates to the user whether the list box or combo box has input focus. The setting 
of the bits in the itemAction member determines whether the rectangle is to be 
drawn as though the list box or combo box has input focus. 


734 CWnd::0nDrawitem 


itemAction 


Defines the drawing action required. This will be one or more of the following 


bits: 
Value 


ODA_DRAWENTIRE 


ODA_FOCUS 


ODA_SELECT 


itemState 


Meaning 


This bit is set when the entire control needs to 
be drawn. 


This bit is set when the control gains or loses 
input focus. The itemState member should be 
checked to determine whether the control has 
focus. 


This bit is set when only the selection status 
has changed. The itemState member should be 
checked to determine the new selection state. 


Specifies the visual state of the item after the current drawing action takes 
place. That is, if a menu item is to be dimmed, the state flag ODS_GRAYED 
will be set. The state flags are: 


| Value 


ODS_CHECKED 
ODS_ DISABLED 


ODS_FOCUS 
ODS_GRAYED 


ODS_SELECTED 


hwndItem 


Meaning 


This bit is set if the menu item is to be checked. 
This bit is used only in a menu. 


This bit is set if the item is to be drawn as 
disabled. 


This bit is set if the item has input focus. 


This bit is set if the item is to be dimmed. This 
bit is used only in a menu. © 


This bit is set if the item’s status is selected. 


For combo boxes, list boxes and buttons, this member specifies the window 
handle of the control; for menus, it contains the handle of the menu (HMENU) 


containing the item. 
hDC 


Identifies a device context; this device context must be used when performing 
drawing operations on the control. 


rcitem 


A rectangle in the device context specified by the hDC member that defines the 
boundaries of the control to be drawn. Windows automatically clips anything 
the owner draws in the device context for combo boxes, list boxes, and buttons, 


See Also 
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Remarks 
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but does not clip menu items. When drawing menu items, the owner must en- 
sure that the owner does not draw outside the boundaries of the rectangle de- 
fined by the rcItem member. 


itemData 
For a combo box or list box, this member contains the value that was passed to 
the list box by one of the following: 


CComboBox::AddString 
CComboBox::InsertString 
ListBox::AddString 
ListBox::InsertString 


For a menu, this member contains the value that was passed to the menu by one 
of the following: 


CMenu::AppendMenu 
CMenu::InsertMenu 
CMenu::ModifyMenu 


This message-handler member function calls Default. Override this member 
function in your derived class to handle the WM_DRAWITEM message. 


DRAWITEMSTRUCT, CWnd::Default, WM_DRAWITEM, 
CWnd::FromHandle, ::FromHandle 


CWnd::OnEnable 


afx_msg void OnEnable( BOOL bEnable ); 


bEnable 
Specifies whether the CWnd has been enabled or disabled. This parameter is 
TRUE if the CWnd has been enabled; it is FALSE if the CWnd has been dis- 
abled. 


Called when an application changes the enabled state of CWnd. It is sent to 
the CWnd whose enabled state is changing. OnEnable is called before the 
EnableWindow member function returns, but after the window enabled state 
(WS_ DISABLE style bit) has changed. 
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See Also 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ENABLE message. 


CWnd::EnableWindow, CWnd::Default, WM_ENABLE 


CWnd::OnEndSession 


afx_msg void OnEndSession( BOOL bEnding ); 


bEnding 
Specifies whether or not the session is being ended. It is TRUE if the session is 
being ended; otherwise, it is FALSE. 


Called after the CWnd has returned TRUE from a OnQueryEndSession member 
function call. The OnEndSession call informs the CWnd whether the session is 
actually ending. 


If bEnding is TRUE, Windows can terminate any time after all applications have 
returned from processing this call. Consequently, have an application perform all 
tasks required for termination within OnEndSession. 


CWnd does not need to call the DestroyWindow member function or 
PostQuitMessage Windows function when the session is ending. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ENDSESSION message. 


CWnd:: Destroy Window, ::ExitWindows, ::PostQuitMessage, 
WM_QUERYENDSESSION, CWnd::Default, WM_ENDSESSION 
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CWnd::OnEnterldle 


afx_msg void OnEnterIdle( UINT nWhy, CWnd* pWho ); 


nWhy 
Specifies whether the message is the result of a dialog box or a menu being dis- 
played. This parameter can be one of the following values: 


Value Description 
MSGF_DIALOGBOX __ The system is idle because a dialog box is being 
displayed. 
MSGF_MENU The system is idle because a menu is being 
displayed. 
pWho 


Specifies a pointer to the dialog box Gif nWhy is MSGF_DIALOGBOX), or 
the window containing the displayed menu (if nWhy is MSGF_MENU). This 
pointer may be temporary, and should not be stored for later use. 


A call to OnEnterIdle informs an application’s main window procedure that a 
modal dialog box or a menu is entering an idle state. A modal dialog box or menu 
enters an idle state when no messages are waiting in its queue after it has 
processed one or more previous messages. 


This message-handler member function calls the Default member function. Over- 
ride this member function in your derived class to handle the WM_ENTERIDLE 
message. 


CWnd::Default, WM_ENTERIDLE 


CWnd::OnEraseBkgnd 


afx_msg BOOL OnEraseBkgnd( CDC* pDC ); 


pDC 
Specifies the device-context object. 


Called when the CWnd background needs erasing (for example, when resized). It 
is called to prepare an invalidated region for painting. 
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This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ERASEBKGND message. 


The Default and DefWindowProc member functions erase the background using 
the class background brush specified by the hbrbackground member of the class 
structure. 


If the hbrbackground member is NULL, OnEraseBkgnd should erase the back- 
ground color. OnEraseBkgnd should align the origin of the intended brush with 
the CWnd coordinates by first calling the UnrealizeObject Windows function for 
the brush, and then selecting the brush. 


Windows assumes the background should be computed by using the MM_ TEXT 
mapping mode. If the device context is using any other mapping mode, the area 
erased may not be within the visible part of the client area. 


OnEraseBkegnd should return TRUE to erase the background; otherwise, it 
should return FALSE. 


::UnrealizeObject, WM_ICONERASEBKGND, CWnd::Default, 
WM_ERASEBKGND, CBrush::FromHandle 


CWnhd::0nFontChange 


afx_msg void OnFontChange(); 


All top-level windows in the system receive an OnFontChan¢ge call after the ap- 
plication changes the pool of font resources. 


An application that adds or removes fonts from the system (for example, through 
the AddFontResource or RemoveFontResource Window function) should send 
the WM_ FONTCHANGE message to all top-level windows. 


To send the WM_ FONTCHANGE message to all top-level windows, an applica- 
tion can use the SendMessage Windows function to send the 
WM_FONTCHANGE message with the }Wnd parameter set to OXFFFF. 
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CWnd::OnGetDigCode 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 


WM_FONTCHANGE message. 


::AddFontResource, ::RemoveFontResource, ::SendMessage, 
CWnd::Default, WM_FONTCHANGE 


CWnd::0nGetDigCode 


afx_msg UINT OnGetDlgCode(Q); 
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Normally, Windows handles all DIRECTION-key and TAB-key input to a CWnd con- 
trol. When OnGetDlgCode is called, a CWnd control can choose a particular 


type of input to process itself. 


Although the Default and DefWindowProc member functions always return 0 in 
response to the WM_GETDLGCODE message, the OnGetDlgCode functions 
for the predefined control classes return a code appropriate for each class. 


OnGetDlgCode’s returned values are useful only with user-defined dialog con- 
trols or standard controls modified by subclassing. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 


WM_GETDLGCODE message. 


One or more of the following values, indicating which type of input the applica- 


tion processes: 


Value 


DLGC_DEFPUSHBUTTON 
DLGC_HASSETSEL 
DLGC_PUSHBUTTON 
DLGC_ RADIOBUTTON 
DLGC_WANTALLKEYS 
DLGC_WANTARROWS 
DLGC_WANTCHARS 


Meaning 


Default push button. 
EM_SETSEL messages. 
Pushbutton. 

Radio button. 

All keyboard input. 
DIRECTION keys. 
WM_CHAR messages. 
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Value Meaning 


DLGC_WANTMESSAGE All keyboard input (the application passes 
this message on to control). 


DLGC_WANTTAB TAB key. 


CWnd::Default, WM_GETDLGCODE 


CWnd::OnGetMinMaxinfo 


afx_msg void OnGetMinMaxInfo( LPPOINT /pPoints ); 


lpPoints 
Points to an array of five POINT structures that contain the following 
information: 


Value Meaning 

apt[0O] This value is reserved for internal use. 

apt[1] Specifies the maximized width (point.x) and the maximized 
height (point.y) of the CWnd. 

apt[2] Specifies the position of the left side of the maximized window 
(point.x) and the position of the top of the maximized window 
(point.y). 

apt[3] Specifies the minimum tracking width (point.x) and the 


minimum tracking height (point.y) of the CWnd. 


apt[4] Specifies the maximum tracking width (point.x) and the 
maximum tracking height (point.y) of the CWnd. 


Called whenever Windows needs to know the maximized position or dimensions, 
or the minimum or maximum tracking size. The maximized size 1s the size of the 
window when its borders are fully extended. The maximum tracking size of the 
window is the largest window size that can be achieved by using the borders to 
size the window. The minimum tracking size of the window is the smallest win- 
dow size that can be achieved by using the borders to size the window. 


Windows fills in an array of points specifying default values for the various posi- 
tions and dimensions. The application may change these values in 
OnGetMinMaxInfo. 


See Also 


Syntax 


Parameters 


Remarks 


CWnd::OnHScroll 741 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_GETMINMAXINFO message. 


CWnd::Default, WM_GETMINMAXINFO 


CWnd::0nHScroll 


afx_msg void OnHScroll( UINT nSBCode, UINT nPos, CWnd* pScrollBar ); 


nSBCode 
Specifies a scroll-bar code that indicates the user’s scrolling request. This 
parameter can be one of the following values: 


Value Description 

SB_ BOTTOM Scroll to lower right. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_ LINEUP Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 
SB_PAGEUP Scroll one page up. 


SB_THUMBPOSITION Scroll to the absolute position. The current 
position is provided in nPos. 


SB_TOP Scroll to upper left. 


nPos 
Specifies the scroll box position if the scroll-bar code is 
SB_THUMBPOSITION; otherwise, not used. 


pScrollBar 
If the control is a scroll bar, contains a pointer to the control. If the user clicked 
a pop-up window’s scroll bar, this parameter is not used. 


Called when the user clicks a window’s horizontal scroll bar. 


The SB_THUMBTRACK notification code typically is used by applications that 
give some feedback while the scroll box is being dragged. 


742 + CWnd::OnHSerollClipboard me 


See Also 


Syntax 


Parameters 


If an application scrolls the contents controlled by the scroll bar, it must also reset 
the position of the scroll box by using the SetScrollPos member function. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_HSCROLL message. 


CWhnd::SetScrollPos, WM_VSCROLL, WM_HSCROLL, CWnd::Default 


CWnhd::0nHScrollClipboard 


afx_msg void OnHScrollClipboard( CWnd* pClipAppWnd, UINT nSBCode, 
UINT nPos ); 


pClipAppWnd 
Specifies a pointer to a Clipboard-viewer window. The pointer may be tem- 
porary, and should not be stored for later use. 


nSBCode 
Specifies one of the following scroll-bar codes in the low-order word: 


Value Description 

SB_ BOTTOM Scroll to lower right. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_ LINEUP Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 
SB_PAGEUP Scroll one page up. 


SB_THUMBPOSITION _ Scroll to the absolute position. The current 
position is provided in nPos. 


SB_ TOP Scroll to upper left. 


nPos 
Contains the scroll box position if the scroll-bar code is 
SB_THUMBPOSITION; otherwise, not used. 


CWnd::OnlconEraseBkgnd 743 


Remarks The Clipboard owner’s OnHScrollClipboard member function is called by the 
Clipboard viewer when the Clipboard data has the CF_OWNERDISPLAY for- 
mat and there is an event in the Clipboard viewer’s horizontal scroll bar. The 
owner should scroll the Clipboard image, invalidate the appropriate section, and 
update the scroll-bar values. 


The Clipboard owner should use the Invalidate or InvalidateRect member func- 
tions, or repaint as desired. The scroll-bar position should also be reset. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_HSCROLLCLIPBOARD message. 


See Also CWhnd::Invalidate, CWnd::OnVScrollClipboard, CWnd::InvalidateRect, 
CWnd::Default, WM_HSCROLLCLIPBOARD 


CWnhd::OniconEraseBkgnd 


Syntax afx_msg void OnIconEraseBkgnd( CDC* pDC ); 


Parameters pDC 
Specifies the device-context object of the icon. May be temporary, and should 
not be stored for later use. 


Remarks Called for a minimized (iconic) CWnd when the background of the icon must 
be filled before painting the icon. CWnd receives this call only if a class icon is 
defined for the window; otherwise, the WM_ERASEBKGND message is sent 
instead. 


The DefWindowProc member function fills the icon background with the back- 
ground brush of the parent window. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ICONERASEBKGND message. 


See Also CWnd::Default, WM_ERASEBKGND, WM_ICONERASEBKGND 


744 CWnd::0ninitMenu 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CWnhd::OninitMenu 


afx_msg void OnInitMenu( CMenu* pMenu ); 


pMenu 
Specifies the menu to be initialized. May be temporary, and should not be 
stored for later use. 


Called when a menu is about to become active. The call occurs when the user 
clicks an item on the menu bar or presses a menu key. Override this member func- 
tion in order to modify the menu before it is displayed. 


OnInitMenu is only called when a menu is first accessed; OnInitMenu is called 
only once for each access. This means, for example, that moving the mouse across 
several menu items while holding down the button does not generate new calls. 
This call does not provide information about menu items. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_INITMENU message. 


CWhnd::OnInitMenuPopup, CWnd::Default, WM_INITMENU 


CWhd::OninitMenuPopup 


afx_msg void OnInitMenuPopup( CMenu* pPopupMenu, UINT nindex, 
BOOL bSysMenu ); 


pPopupMenu 
Specifies the menu object of the pop-up menu. May be temporary, and should 
not be stored for later use. 


nIndex 
Specifies the index of the pop-up menu in the main menu. 


bSysMenu 
TRUE if the pop-up menu is the system menu; otherwise FALSE. 


Called when a pop-up menu is about to become active. This allows an application 
to modify the pop-up menu before it is displayed, without changing the 
entire menu. 


See Also 


Syntax 


Parameters 


CWnd::OnKeyDown 745 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_INITMENUPOPUP message. 


CWnd::OnInitMenu, CWnd::Default, WM_INITMENUPOPUP 


CWnd::0nKeyDown 


afx_msg void OnKeyDown( UINT nChar, UINT nRepCnt, UINT nFlags ); 


nChar 


Specifies the virtual-key code of the given key. 


nRepCnt 


Repeat count (the number of times the keystroke is repeated as a result of the 
user holding down the key). 


nFlags 


Specifies the scan code, key-transition code, previous key state, and context 
code, as shown in the following list: 


Value 


15 


Description 
Scan code (OEM-dependent value). 


Extended key, such as a function key or a key on the numeric 
keypad (1 if it is an extended key). 


Not used. 
Used internally by Windows. 


Context code (1 if the ALT Key is held down while the Key is 
pressed, O otherwise). 


Previous key state (1 if the key is down before the call, 0 if the 
key is up). 


Transition state (1 if the key is being released, 0 if the key is 
being pressed). 


For a WM_KEYDOWN message, the key-transition bit (bit 15) is O and the 
context-code bit (bit 13) is 0. 


746 CWnd::0nKeyUp 


Remarks Called when a nonsystem key is pressed. A nonsystem key is a keyboard key that 
is pressed when the ALT key is not pressed, or a keyboard key that is pressed when 
CWnd has the input focus. 


Because of auto-repeat, more than one OnKeyDown call may occur before an 
OnkKeyUp member function call is made. The bit indicating the previous key state 
can be used to determine whether the OnKeyDown call indicates the first down 
transition or a repeated down transition. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
and the right CONTROL keys on the main section of the keyboard; the INSERT, 
DELETE, HOME, END, PAGE UP, PAGE DOWN, and ARROW keys in the clusters to the 
left of the numeric keypad; and the slash (/) and ENTER keys in the numeric key- 
pad. Some other keyboards may support the extended-key bit in nFlags. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_KEYDOWN message. 


See Also WM_CHAR, WM_KEYUP, CWnd::Default, WM_KEYDOWN 


CWnd::0nKeyUp 


Syntax afx_msg void OnKeyUp( UINT nChar, UINT nRepCnt, UINT nFlags ); 
Parameters nChar 
Specifies the virtual-key code of the given key. 
nRepCnt 


Repeat count (the number of times the keystroke is repeated as a result of the 
user holding down the key). 


nFlags 
Specifies the scan code, key-transition code, previous key state, and context 
code, as shown in the following list: 


Value Description 

O-7 Scan code (OEM-dependent value). Low byte of high-order 
word. 

8 Extended key, such as a function key or a key on the numeric 


keypad (1 if itis an extended key; 0 otherwise). 
9-10 Not used. 


CWhd::OnKillFocus 747 


Value Description 

11-12 Used internally by Windows. 

13 Context code (1 if the ALT key is held down while the key is 
pressed, 0 otherwise). 

14 Previous key state (1 if the key is down before the call, 0 if the 
key is up). 

15 Transition state (1 if the key is being released, 0 if the key is 
being pressed). 


For a WM_KEYUP message, the key-transition bit (bit 15) is 1 and the con- 
text-code bit (bit 13) 1s 0. 


Remarks Called when a nonsystem key is released. A nonsystem key is a keyboard key that 
is pressed when the ALT key is not pressed, or a keyboard key that is pressed when 
the CWnd has the input focus. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
and the right CONTROL keys on the main section of the keyboard; the INSERT, 
DELETE, HOME, END, PAGE UP, PAGE DOWN, and ARROW keys in the clusters to the 
left of the numeric keypad; and the slash (/) and ENTER keys in the numeric Key- 
pad. Some other keyboards may support the extended-key bit in nFlags. 


This message-handler member function calls the Default member function. Over- 


ride this member function in your derived class to handle the WM_KEYUP 
message. 


See Also WM_ CHAR, WM_KEYUP, CWnd::Default, WM_KEYDOWN 


CWnd::OnkillFocus 


Syntax afx_msg void OnKillFocus( CWnd* pNewWnd ); 


Parameters pNewWnd 


Specifies a pointer to the window that receives the input focus (may be NULL 
or may be temporary). 


748 CWnd::OnLButtonDbIiClk 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Called immediately before losing the input focus. 


If the CWnd object is displaying a caret, the caret should be destroyed at this 
point. 


This message-handler member function calls the Default member function. 


Override this member function in your derived class to handle the 
WM_KILLFOCUS message. 


CWnd::SetFocus, CWnd::Default, WM_KILLFOCUS 


CWnd::0nLButtonDbIiClk 


afx_msg void OnLButtonDbICIk( UINT nFlags, CPoint point ); 


nFlags iiten | 
Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Value Description 
MK_CONTROL Set if CONTROL Key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_ SHIFT Set if SHIFT key is down. 

point 


Specifies the x- and y-coordinate of the cursor. These coordinates are always 
relative to the upper-left corner of the window. 


Called when the user double-clicks the left mouse button. 


Only windows that have the CS_DBLCLKS WNDCLASS style will receive 
OnLButtonDbICIk calls. This is the default for Microsoft Foundation Class win- 
dows. Windows calls OnLButtonDbIClIk when the user presses, releases, and 
then presses the left mouse button again within the system’s double-click time 
limit. Double-clicking the left mouse button actually generates four events: 
WM_LBUTTONDOWN, WM_LBUTTONUP messages, the 
WM_LBUTTONDBLCLK call, and another WM_LBUTTONUP 

message when the button is released. 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


CWnd::0nLButtonDown 749 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_LBUTTONDBLCLK message. 


CWnd::OnLButtonDown, CWnd::OnLButtonUp, CWnd::Default, 
WM_LBUTTONDBLCLK 


CWnd::0nLButtonDown 


afx_msg void OnLButtonDown( UINT nFlags, CPoint point ); 


nFlags 
Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Value Description 
MK_CONTROL Set if CONTROL Key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_SHIFT Set if SHIFT key is down. 

point 


Specifies the x- and y-coordinate of the cursor. These coordinates are always 
relative to the upper-left corner of CWnd. 


Called when the user presses the left mouse button. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_LBUTTONDOWN message. 


CWnd::OnLButtonDbIClk, CWnd::OnLButtonUp, 
WM_LBUTTONDOWN, CWnd::Default 


750 


Syntax 


CWnd::0nLButtonUp 


CWnhd::OnLButtonUp 


afx_msg void OnLButtonUp( UINT nFlags, CPoint point ); 


Parameters nFlags 


Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Remarks 


See Also 


Value 
MK_CONTROL 
MK_LBUTTON 
MK_MBUTTON 
MK_RBUTTON 
MK_SHIFT 


point 


Description 

Set if CONTROL Key is down. 

Set if left mouse button is down. 
Set if middle mouse button is down. 
Set if right mouse button is down. 


Set if SHIFT key is down. 


Specifies the x- and y-coordinate of the cursor. These coordinates are always 
relative to the upper-left corner of CWnd. 


Called when the user releases the left mouse button. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_LBUTTONUP message. 


CWnd::OnLButtonDbIClk, CWnd::OnLButtonDown, WM_LBUTTONUP, 


CWnad::Default 


Syntax 


Parameters 


Remarks 


See Also 


CWnd::OnMButtonDbiCik 751 


CWnd::OnMButtonDbiClk 


afx_msg void OnMButtonDbICIk( UINT nFlags, CPoint point ); 


nFlags 
Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Value Description 
MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_SHIFT Set if SHIFT key is down. 

point 


Specifies the x- and y-coordinates of the cursor. These coordinates are always 
relative to the upper-left corner of CWnd. 


Called when the user double-clicks the middle mouse button. 


Only windows that have the CS_DBLCLKS WNDCLASS style will receive 
OnMButtonDbIClk calls. This is the default for all Microsoft Foundation Class 
Library windows. Windows generates a OnMButtonDbICIk call when the user 
presses, releases, and then presses the middle mouse button again within the sys- 
tem’s double-click time limit. Double-clicking the middle mouse button actually 
generates four events: WM_MBUTTONDOWN and WM_MBUTTONUP mes- 
sages, the WM_MBUTTONDBLCLK call, and another WM_MBUTTONUP 
message. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MBUTTONDBLCLK message. 


CWhnd::Default, CWnd::OnMButtonDown, CWnd::OnMButtonUp, 
WM_MBUTTONDBLCLK 


752 CWnd::OnMButtonDown 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


CWnd::OnMButtonDown 


afx_msg void OnMButtonDown( UINT nFlags, CPoint point ); 


nFlags 
Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Value Description 
MK_ CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_SHIFT Set if SHIFT key is down. 

point 


Specifies the x- and y-coordinate of the cursor. These coordinates are always 
relative to the upper-left corner of CWnd. 


Called when the user presses the middle mouse button. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MBUTTONDOWN message. 


CWnd::OnMButtonDbICIk, CWnd::OnMButtonUp, CWnd::Default, 
WM_MBUTTONDOWN 


CWhd::O0nMButtonUp 


afx_msg void OnMButtonUp( UINT nFlags, CPoint point ); 


nFlags 


Indicates whether various virtual keys are down. This parameter can be any 
— combination of the following values: 


Remarks 


See Also 


Syntax 


Parameters 


CWnd::OnMDIActivate 753 


Value Description 
MK_CONTROL Set if CONTROL Key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_SHIFT Set if SHIFT key 1s down. 

point 


Specifies the x- and y-coordinate of the cursor. These coordinates are always 
relative to the upper-left corner of CWnd. 


OnMButtonUp is called when the user releases the middle mouse button. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MBUTTONUP message. 


CWnd::OnMButtonDbICIk, CWnd::OnMButtonDown, CWnd::Default, 
WM_MBUTTONUP 


CWnd::0nMDIActivate 


afx_msg void OnMDIActivate( BOOL bActivate, CWnd* pActivatedWnd, 
CWnd* pDeactivatedWnd ); 


bActivate 
When the client window calls a child window’s OnMDIActivate member func- 
tion, bActivate is TRUE if the child is being activated and FALSE if it is being 
deactivated. 


pActivatedWnd 
When the application calls its MDI client window’s OnMDIActivate member 
function, pActivatedWnd contains a pointer to the MDI child window to be acti- 
vated. When received by an MDI child window, pActivatedWnd contains a 
pointer to the child window being activated. This pointer may be temporary, 
and should not be stored for later use. 


754 CWnd::OnMeasureltem 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


pDeactivatedWnd 
When received by an MDI child window, pDeactivatedWnd contains a pointer 
to the child window being deactivated. This pointer may be temporary, and 
should not be stored for later use. 


An application calls the multiple document interface (MDI) 
CMDIFrameWnd::MDIActivate member function to activate a different MDI 
child window. The OnMD1IActivate member function is called for the child win- 
dow being deactivated and the child window being activated. 


An MDI child window is activated independently of the MDI frame window. 
When the frame becomes active, the child window that was last activated with 
a OnMDtIActivate call receives a WM_NCACTIVATE message to draw an 
active window frame and caption bar, but it does not receive another 
OnMDtIActivate call. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MDIACTIVATE message. 


CMDIFramewWwnd::MDIGetActive, CMDIFrameWnd::MDINext, 
CMDIFrameWwnd::MDtIActivate, WM_MDIACTIVATE, CWnd::Default 


CWnd::0nMeasureltem 


afx_ msg void OnMeasureltem 
(LPMEASUREITEMSTRUCT /[pMeasureltemStruct ); 


lpMeasurelItemStruct 
Specifies a long pointer to a MEASUREITEMSTRUCT data structure that 
contains the dimensions of the owner-draw control. 


Called for the owner of an owner-draw button, combo box, list box, or menu 

item when the control is created. When the owner receives the call, the owner 
should fill in the MEASUREITEMSTRUCT data structure pointed to by 
[pMeasureltemStruct and return; this informs Windows of the dimensions of the 
control and allows Windows to process user interaction with the control correctly. 


If a list box or combo box is created with the LBS_ OWNERDRAWVARIABLE 
or CBS_OWNERDRAWVARIABLE style, this function is called for the owner 
for each item in the control; otherwise, this function is called once. 


Members 


CWnd::0nMeasureltem 755 


Windows calls OnMeasurelItem for the owner of combo boxes and list 

boxes created with the OWNERDRAWFIXED style before sending the 
WM_INITDIALOG message. As a result, when the owner receives this call, 
Windows has not yet determined the height and width of the font used in the con- 
trol; function calls and calculations requiring these values should occur in the main 
function of the application or library. 


A MEASUREITEMSTRUCT data structure has the following form: 


typedef struct tagMEASUREITEMSTRUCT { 
WORD CtlType; 
WORD CULED- 
WORD itemID; 
WORD itemWidth; 
WORD itemHeight; 
DWORD itemData 
} MEASUREITEMSTRUCT; 


CtlType 
Is the control type. The values for control types are as follows: 
Value Meaning 
ODT_BUTTON Owner-draw button. 
ODT_COMBOBOX Owner-draw combo box. 
ODT_LISTBOX Owner-draw list box. 
ODT_MENU Owner-draw menu. 

CtlID 


Is the control ID for a combo box, list box, or button. This member is not used 
for a menu. 


itemID 
Is the menu-item ID for a menu or the list box item ID for a variable-height 
combo box or list box. This member is not used for a fixed-height combo box 
or list box, or for a button. 


item Width 
Specifies the width of a menu item. The owner of the owner-draw menu item 
must fill this member before returning from the message. 


item Height 
Specifies the height of an individual item in a list box or a menu. Before return- 
ing from the message, the owner of the owner-draw combo box, list box, or 
menu item must fill out this member. The maximum height of a list box item 
is 255. 


756 CWnd::OnMenuChar 


Comments 


See Also 


Syntax 


Parameters 


Remarks 


itemData 
For a combo box or list box, this member contains the value that was passed to 
the list box by one of the following: 


CComboBox::AddString 
CComboBox:: InsertString 
ListBox::AddString 
ListBox: :InsertString 


For a menu, this member contains the value that was passed to the menu by one 
of the following: 


CMenu::AppendMenu 
CMenu::InsertMenu 
CMenu::ModifyMenu 


Failure to fill out the proper members in the MEASUREITEMSTRUCT struc- 
ture will cause improper operation of the control. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MEASUREITEM message. 


WM_INITDIALOG, CWnd::Default, WM_MEASUREITEM 


CWnhd::OnMenuChar 


afx_msg LONG OnMenuChar( UINT nChar, UINT nFlags, CMenu* pMenu ); 


nChar 
Specifies the ASCII character that the user pressed. 


nFlags 
Contains the MF_ POPUP flag if the menu is a pop-up menu. It contains the 
MF_SYSMENU flag if the menu is a Control menu. 


pMenu 
Contains a pointer to the selected CMenu. The pointer may be temporary, and 
should not be stored. 


Called when the user presses a menu mnemonic character that doesn’t match any 
of the predefined mnemonics in the current menu. It is sent to the CWnd that 
owns the menu. 


CWnd::0nMenuSelect 757 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MENUCHAR message. 


Return Value The high-order word of the return value should contain one of the following com- 
mand codes: 


Value Description 


0 Tells Windows to discard the character that the user pressed, and 
creates a short beep on the system speaker. 


Tells Windows to close the current menu. 


2 Informs Windows that the low-order word of the return value 
contains the menu item-number for a specific item. This item is 
selected by Windows. 


The low-order word is ignored if the high-order word contains 0 or 1. Applications 
should process this message when accelerators are used to select bitmaps placed in 
a menu. 


See Also CWnd::Default, WM_MENUCHAR 


CWnd::OnMenuSelect 


syntax afx_msg void OnMenuSelect( UINT nitemID, UINT nFlags, 
HMENU /SysMenu ); 
Parameters nltemID 


Identifies the item selected. If the selected item is a menu item, n/temID con- 
tains the menu-item ID. If the selected item contains a pop-up menu, n/temID 
contains the pop-up menu handle. 


nFlags 
Contains a combination of the following menu flags: 
Flag Description 
MF_ BITMAP Item is a bitmap. 
MF_CHECKED Item is checked. 


MF_DISABLED Item is disabled. 


758 CWnd::O0nMouseActivate 


Remarks 


See Also 


Syntax 


Parameters 


Flag Description 
MF_GRAYED Item is dimmed. 
MF_MOUSESELECT Item was selected with a mouse. 
MF_OWNERDRAW Item is an owner-draw item. 
MF_POPUP Item contains a pop-up menu. 
MF_SEPARATOR Item is a menu-item separator. 
MF_SYSMENU Item is contained in the Control menu. 
hSysMenu 


Identifies the menu associated with the message, if nFlags contains 
MF_SYSMENU. 


If the CWnd is associated with a menu, OnMenuSelect is called when the user 
selects a menu item. 


If nFlags contains —1 and hSysMenu contains 0, Windows has closed the menu be- 
cause the user pressed ESC or clicked outside the menu. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MENUSELECT message. 


CWnd::Default, WM_MENUSELECT, CMenu::FromHandle 


CWnd::OnMouseActivate 


afx_msg int OnMouseActivate( CWnd* pF rameWnd, UINT nHitTest, 
UINT message ); 


pFrameWnd 
Specifies a pointer to the topmost parent window of the window being acti- 
vated. The pointer may be temporary, and should not be stored. 


nHitTest 
Specifies the hit-test area code. A hit test is a test that determines the location of 
the cursor. 


message 
Specifies the message number. 


Remarks 


Return Value 


See Also 


CWnd::0nMouseActivate 759 


Called when the cursor is in an inactive window and the user presses a mouse 
button. 


If the child window passes the message to the Default or DefWindowProc mem- 
ber function, Default or DefWindowProc passes this message to the CWnd 
parent window before any processing occurs. If the parent window returns TRUE, 
processing is halted. 


For a description of the individual hit-test area codes, see the OnNcHitTest mem- 
ber function. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MOUSEACTIVATE message. 


Specifies whether to activate the CWnd and whether to discard the mouse event. 
It must be one of the following values: 


Value Meaning 

MA_ ACTIVATE Activate CWnd. 

MA_NOACTIVATE Do not activate CWnd. 

MA_ACTIVATEANDEAT Activate CWnd and discard the mouse 
event. 


MA_NOACTIVATEANDEAT Do not activate CWnd and discard the 
mouse event. 


CWnd::OnNcHitTest, CWnd::Default, WM_MOUSEACTIVATE 


760 CWhd::OnMouseMove 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


CWnd::OnMouseMove 


afx_msg void OnMouseMove( UINT nFlags, CPoint point ); 


nFlags 


Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Value Description 
MK_CONTROL Set if CONTROL Key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_ SHIFT Set if SHIFT key is down. 

point 


Specifies the x- and y-coordinates of the cursor. These coordinates are always 
relative to the upper-left corner of the window. 


Called when the mouse cursor moves. If the mouse is not captured, the 
WM_MOUSEMOVE is sent to the CWnd beneath the mouse pointer; other- 
wise, the message goes to the mouse-capture window. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_MOUSEMOVE message. 


CWnd::SetCapture, CWnd::OnNCHitTest, WM_MOUSEMOVE, 
CWhnd::Default 


CWnd::OnMove 


afx_msg void OnMove( int x, int y ); 


x 
Specifies the new x-coordinate location of the upper-left corner of the client 
area. This new location is given in screen coordinates for overlapped and pop- 
up windows, and parent-client coordinates for child windows. 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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Specifies the new y-coordinate location of the upper-left corner of the client 
area. This new location is given in screen coordinates for overlapped and pop- 
up windows, and parent-client coordinates for child windows. 


Called after CWnd has been moved. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the WM_MOVE 
message. 


CWnd::Default, WM_MOVE 


CWnd::OnNecActivate 


afx_msg BOOL OnNcActivate( BOOL bActive ); 


bActive 
Specifies when a caption bar or icon needs to be changed to indicate an active 
or inactive state. The bActive parameter is TRUE if an active caption or icon is 
to be drawn. It is FALSE for an inactive caption or icon. 


Called when the nonclient area needs to be changed to indicate an active or inac- 
tive state. 


The Default member function draws the appropriate caption bar. 


This message-handler member function calls the Default member function. 
Override this member function 1n your derived class to handle the 
WM_NCACTIVATE message. 


TRUE if activation should proceed; FALSE if activation should be aborted. 


CWnd::Default, WM_NCACTIVATE 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


CWnd::0nNcCalcSize 


afx_msg void OnNcCalcSize( LPRECT /pRect ); 


lpRect 
Points to a RECT data structure that contains the screen coordinates of the 
CWnd rectangle (including client area, borders, caption, scroll bars, and so on). 


Called when the size of the client area needs to be calculated. 


The Default member function calculates the size of the client area based on the 
window characteristics (presence of scroll bars, menu, and so on), and places the 
result in /pRect. 


This message-handler member function calls the Default member function. 


Override this member function in your derived class to handle the 
WM_NCCALCSIZE message. 


CWhnd::Default, WM_NCCALCSIZE 


CWnd::0OnNcCreate 


afx_msg BOOL OnNcCreate( LPCREATESTRUCT [pCreateStruct ); 


lpCreateStruct 7 
Points to the CREATESTRUCT data structure for CWnd. 


Called prior to the WM_CREATE message when the CWnd is first created. 


By default, scroll bars are initialized (the scroll-bar position and range are set) and 
the CWnd text is set. Memory used internally to create and maintain the window 
is allocated. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCCREATE message. 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 
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TRUE if the nonclient area is created. It is FALSE if an error occurs; the Create 
function will return NULL in this case. 


CWnd::CreateEx, WM_NCCREATE, CWnd::Default 


CWnd::OnNeDestroy 


afx_msg void OnNcDestroy(); 


Called when the nonclient area is being destroyed. The DestroyWindow member 
function sends WM_NCDESTROY. 


The Default member function frees any memory internally allocated for the 
Windows window. 


The OnNecDestroy member function is the last member called when the Windows 
window is being destroyed. OnNecDestroy can call delete this to free the CWnd 
object that was dynamically allocated with new. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCDESTROY message. 


CWnd::DestroyWindow, CWnd::OnNcCreate, WM_NCDESTROY, 
CWnd:: Default 


CWnd::OnNecHitTest 


afx_msg UINT OnNcHitTest( CPoint point ); 


point 
Contains the x- and y-coordinates of the cursor. These coordinates are always 
screen coordinates. 


Called for the CWnd that contains the cursor (or the CWnd that used the 
SetCapture member function to capture the mouse input) every time the mouse is 
moved. 
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Return Value 


See Also 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCHITTEST message. 


One of the following values: 


Value 


HTBOTTOM 


HTBOTTOMLEFT 
HTBOTTOMRIGHT 


HTCAPTION 
HTCLIENT 
HTERROR 


HTGROWBOX 
HTHSCROLL 
HTLEFT 
HTMENU 
HTNOWHERE 


HTREDUCE 
HTRIGHT 
HTSIZE 
HTSYSMENU 
HTTOP 
HTTOPLEFT 
HTTOPRIGHT 


HTTRANSPARENT 


HTVSCROLL 
HTZOOM 


Meaning 


In the lower horizontal border of the window. 
In the lower-left corner of the window border. 
In the lower-right corner of the window border. 
In a caption area. 

In a client area. 


Same as HTNOWHERE except that the 
DefWindowProc member function produces a 
system beep to indicate an error. 


In a size box. 

In the horizontal scroll bar. 

In the left border of the window. 
In a menu area. 


On the screen background or on a dividing line 
between windows. 


In a Minimize button. 
In the right border of the window. 
Same as HTGROWBOX. 


In a Control-menu box (close box in child windows). 


In the upper horizontal border of the window. 
In the upper-left corner of the window border. 


In the upper-right corner of the window border. 


In a window currently covered by another window. 


In the vertical scroll bar. 


In a Maximize button. 


CWnd::Default, CWnd::GetCapture, WM_NCHITTEST 


syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 
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CWnd::OnNcLButtonDbiClk 


afx_msg void OnNcLButtonDbICIk( UINT nHitTest, CPoint point ); 


nHitTest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 

point 
Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Called when the user double-clicks the left mouse button while the cursor is within 
a nonclient area of CWnd. 


If appropriate, the WM_SYSCOMMAND message is sent. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCLBUTTONDBLCLK message. 


CWnd::Default, WM_NCLBUTTONDBLCLK, CWnd::OnNcHitTest 


CWnhd::OnNcLButtonDown 


afx_msg void OnNcLButtonDown( UINT nHitTest, CPoint point ); 


nHfitlest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 

point 
Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Called when the user presses the left mouse button while the cursor is within a 
nonclient area of CWnd. 


If appropriate, the WM_SYSCOMMAND 1s sent. 
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This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCLBUTTONDOWN message. 


See Also CWnd::OnNcHitTest, CWnd::OnNcLButtonDbIClk, 


CWnd::OnNcLButtonUp, CWnd::OnSysCommand, 
WM_NCLBUTTONDOWN, CWnad::Default 


CWhd::OnNecLButtonUp 


Syntax afx_msg void OnNcLButtonUp( UINT nHitTest, CPoint point ); 
Parameters nHitTest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 
point 


Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Remarks Called when the user releases the left mouse button while the cursor is within a 
nonclient area. 


If appropriate, WM_SYSCOMMAND 1s sent. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCLBUTTONUP message. 


See Also CWnd::OnNcHitTest, CWnd::OnNcLButtonDown, 
CWnd::OnSysCommand, CWnd::Default, WM_NCLBUTTONUP 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 
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CWnd::OnNcMButtonDbIiClk 


afx_ msg void OnNcMButtonDbICIk( UINT nHitTest, CPoint point ); 


nHitTest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 

point 
Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Called when the user double-clicks the middle mouse button while the cursor is 
within a nonclient area. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCMBUTTONDBLCLK message. 


CWnd::OnNcHitTest, CWnd::OnNcMButtonDown, 
CWnd::OnNcMButtonUp, WM_NCMBUTTONDBLCLK, CWnd::Default 


CWnd::OnNeMButtonDown 


afx_msg void OnNcMButtonDown( UINT nHitTest, CPoint point ); 


nHitlest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 


point 
Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 
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Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


Called when the user presses the middle mouse button while the cursor is within a 
nonclient area. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCMBUTTONDOWN message. 


CWnd::OnNcHitTest, CWnd::OnNcMButtonUp, 
WM_NCMBUTTONDOWN, CWnd::Default 


CWhd::OnNcMButtonUp 


afx_msg void OnNcMButtonUp( UINT nHitTest, CPoint point ); 


nHitTest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 

point 
Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Called when the user releases the left mouse button while the cursor is within a 
nonclient area. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCMBUTTONUP message. 


CWnd::OnNcHitTest, CWnd::OnNcMButtonDbIClk, 
CWnd::OnNcMButtonDown, WM_NCMBUTTONUP, CWnd::Default 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


See Also 
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CWnd::OnNcMouseMove 


afx_msg void OnNcMouseMove( UINT nHitTest, CPoint point ); 


nHitlest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 


point 
Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Called when the cursor is moved within a nonclient area. 
If appropriate, the WM_SYSCOMMAND message is sent. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCMOUSEMOVE message. 


CWnd::OnNcHitTest, CWnd::OnSysCommand, WM_NCMOUSEMOVE, 
CWhnd::Default 


CWnhd::OnNePaint 


afx_msg void OnNcPaint(); 


Called when the nonclient area needs to be painted. 


An application can override this call and paint its own custom window frame. The 
clipping region is always rectangular, even if the shape of the frame is altered. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCPAINT message. 


CWnd::Default, WM_NCPAINT 
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CWnd::OnNcRButtonDbiClk 


Syntax afx_msg void OnNcRButtonDbIClk( UINT nHitTest, CPoint point ); 
Parameters nHitTest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 
point 


Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Remarks Called when the user double-clicks the right mouse button while the cursor is 
within a nonclient area of CWnd. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCRBUTTONDBLCLK message. 


See Also CWnd::OnNcHitTest, CWnd::OnNcRButtonDown, 
CWnd::OnNcRButtonUp, CWnd::Default, WM_NCRBUTTONDBLCLK 


CWnd::0nNcRButtonDown 


Syntax afx_ msg void OnNcRButtonDown( UINT nHitTest, CPoint point ); 
Parameters nHitTest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 
point 


Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 
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Called when the user presses the right mouse button while the cursor is within a 
nonclient area. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCRBUTTONDOWN message. 


CWnd::OnNcHitTest, CWnd::OnNcRButtonDbIClk, 
CWnd::OnNcRButtonUp, CWnd::Default, WM_NCRBUTTONDOWN 


CWnd::OnNeRButtonUp 


afx_ msg void OnNcRButtonUp( UINT nAHitTest, CPoint point ); 


nHitlest 
Specifies the hit-test code. A hit test is a test that determines the location of the 
cursor. 


point 
Specifies a CPoint that contains the x and y screen coordinates of the cursor 
position. These coordinates are always relative to the upper-left corner of the 
screen. 


Called when the user releases the right mouse button while the cursor is within a 
nonclient area. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_NCRBUTTONUP message. 


CWnd::OnNcHitTest, CWnd::OnNcRButtonDbIClIk, 
CWnd::OnNcRButtonDown, CWnd::Default, WM_NCRBUTTONUP 
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CWnd::0nPaint 


Syntax afx_msg void OnPaint(); 
Remarks Called when Windows or an application makes a request to repaint a portion of the 
CWnd. 


The WM_PAINT message is sent to this member function when the 
UpdateWindow member function is called, or when the update region is not 
empty and there are no pending messages. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the WM_ PAINT 
message. 


See Also CWnd::UpdateWindow, CPaintDC, CWnd::Default, WM_ PAINT 


CWnd::OnPaintClipboard 


Syntax afx_ msg void OnPaintClipboard( CWnd* pClipAppWnd, 
HANDLE /PaintStruct ); 


Parameters pClipAppWnd 
Specifies a pointer to the Clipboard-application window. The pointer may be 
temporary, and should not be stored for later use. 


hPaintStruct | 
Identifies a PAINTSTRUCT data structure that defines what part of the client 
area to paint. 


Remarks A Clipboard owner’s OnPaintClipboard member function is called by a Clip- 
board viewer when the owner has placed data on the Clipboard in the 
CF_OWNERDISPLAY format and the Clipboard viewer’s client area needs 
repainting. 


To determine whether the entire client area or just a portion of it needs repainting, 
the Clipboard owner must compare the dimensions of the drawing area given in 
the repaint member of the PAINTSTRUCT structure to the dimensions given in 
the most recent OnSizeClipboard member function call. 


See Also 
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Remarks 
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Remarks 
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OnPaintClipboard should use the GlobalLock Windows function to lock the 
memory that contains the PAINTSTRUCT data structure, and unlock that 
memory by using the GlobalUnlock Windows function before it exits. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_PAINTCLIPBOARD message. 


::GlobalLock, ::GlobalUnlock, CWnd::OnSizeClipboard, 
WM_PAINTCLIPBOARD, CWnd::Default 


CWnd::0nPainticon 


afx_msg void OnPaintIcon(Q); 


Called by a minimized (iconic) CWnd when the icon is to be painted. 


A window receives this call only if a class icon is defined for the window; other- 
wise, the OnPaint member function is called instead. OnPaintIcon permits 
Windows to paint the icon with the class icon. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_PAINTICON message. 


WM_PAINT, WM_PAINTICON, CWnd::Default 


CWnd::OnPaletteChanged 


afx_msg void OnPaletteChanged( CWnd* pFocusWnd ); 


pFocusWnd 
Specifies a pointer to the window that caused the system palette to change. The 
pointer may be temporary, and should not be stored. 


Called after the window with input focus has realized its logical palette, thereby 
changing the system palette. This call allows windows without the input focus that 
use a color palette to realize their logical palettes and update their client areas. 
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To avoid creating a loop, CWnd shouldn’t realize its palette unless it determines 
that pFocusWnd does not contain a pointer to itself. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_PALETTECHANGED message. 


See Also ::RealizePalette, WM_PALETTECHANGED, CWhnd::Default 


CWnd::0nParentNotify 


Syntax afx_msg void OnParentNotify( UINT message, LONG /Param ); 

Parameters message 
Specifies the event for which the parent is being notified. It can be any of these 
values: 
Value Description 
WM_ CREATE The child window is being created. 
WM_DESTROY The child window is being destroyed. 
WM_LBUTTONDOWN The user has placed the mouse cursor over 


the child window and clicked the left 
mouse button. 


WM_MBUTTONDOWN The user has placed the mouse cursor over 
the child window and clicked the middle 
mouse button. 


WM_RBUTTONDOWN The user has placed the mouse cursor over 
the child window and clicked the night 
mouse button. 


[Param 
Specifies the window handle of the child window in the low-order word and the 
identifier of the child window in the high-order word if message is 
WM_CREATE or WM_ DESTROY; otherwise, /Param contains the x- and 
y-coordinates of the cursor. The x-coordinate is in the low-order word and the 
y-coordinate is in the high-order word. 


Remarks A parent’s OnParentNotify member function is called when its child window is 
created or destroyed, or when the user clicks a mouse button while the cursor is 


See Also 


Syntax 


Remarks 


Return Value 
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over the child window. When the child window is being created, the system calls 
OnParentNotify just before the Create member function that creates CWnd 
returns. When the child window is being destroyed, the system calls 
OnParentNotify before any processing takes place to destroy CWnd. 


OnParentNotify is called for all ancestor windows of the child window, including 
the top-level window. 


All child windows except those that have the WS_EX_NOPARENTNOTIFY 
style send this message to their parent windows. By default, child windows in a 
dialog box have the WS_EX_ NOPARENTNOTIFY style unless the child win- 
dow was created without this style by calling the CreateEx member function. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_PARENTNOTIFY message. 


CWnd::CreateEx, CWnd::OnCreate, CWnd::OnDestroy, 
CWnd::OnLButtonDown, CWnd::OnMButtonDown, 
CWnd::OnRButtonDown, WM_PARENTNOTIFY, CWnd::Default 


CWnd::O0nQueryDraglcon 
afx_msg HCURSOR OnQueryDragIcon(); 


Called by a minimized (iconic) CWnd if it is about to be dragged by the user and 
it does not have an icon defined for its class. The system makes this call to obtain 
the cursor to display while the user drags the minimized window. 


If an application returns an icon handle, the system converts the icon to a black- 
and-white cursor. 


If an application returns a handle, the handle must identify a monochrome cursor 
or icon compatible with the display driver’s resolution. The application can call 
the CWinApp::LoadCursor or CWinApp::LoadIcon member functions to load 
a cursor or icon from the resources in its executable file and to obtain this handle. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ QUERYDRAGICON message. 


Returns a cursor or icon handle. If NULL is returned, the system displays the de- 
fault cursor. The default return value is NULL. 
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CWinApp::LoadCursor, CWinApp::LoadIcon, WM_QUERYDRAGICON, 
CWnad:: Default 


CWnd::OnQueryEndSession 


afx_msg BOOL OnQueryEndSession(); 


Called when the user chooses to end the Windows session or when an application 
calls the ExitWindows Windows function. If any application returns FALSE, the 
Windows session is not ended. Windows stops calling OnQueryEndSession as 
soon as one application returns FALSE, and sends the WM_ENDSESSION mes- 
sage with a parameter value of FALSE for any applications that have already re- 
turned TRUE. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_QUERYENDSESSION message. 


An application should return TRUE if it can be conveniently shut down; other- 
wise FALSE. 


CWnd::Default, ::ExitWindows, CWnd::OnEndSession, 
WM_QUERYENDSESSION 
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CWnd::0nQueryNewPalette 


afx_msg BOOL OnQueryNewPalette(); 


Called when the CWnd is about to receive the input focus. If the CWnd realizes 
its logical palette when it receives the input focus, it should return TRUE; other- 
wise, it should return FALSE. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_QUERYNEWPALETTE message. 


TRUE if the CWnd realizes its logical palette; otherwise FALSE. 


CWnd::Default, WM_QUERYNEWPALETTE 


CWhd::OnQueryOpen 


afx_msg BOOL OnQueryOpen(); 


Called when the CWnd is iconized and the user requests that the CWnd be 
opened into a window. 


While in OnQueryOpen, CWnd should not perform any action that would cause 
an activation or focus change (for example, creating a dialog box). 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_QUERYOPEN message. 


TRUE if the icon can be opened, or FALSE to prevent the icon from being 
opened. 


CWhnd::Default, WM_QUERYOPEN 
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CWnd::OnRButtonDbiClk 


CWnd::0OnRButtonDbIiClk 


afx_msg void OnRButtonDbICIk( UINT nFlags, CPoint point ); 


nFlags 
Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Value ‘Description 
MK_ CONTROL Set if CONTROL Key is down. 
MK_ LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_SHIFT Set if SHIFT key 1s down. 

point 


Specifies the x- and y-coordinates of the cursor. These coordinates are always 
relative to the upper-left corner. 


Called when the user double-clicks the right mouse button. 


Only windows that have the CS_DBLCLKS class style can receive 
OnRButtonDbICIk calls. This is the default for windows within the Microsoft 
Foundation Class Library. Windows calls OnRButtonDbICIk when the user 
presses, releases, and then presses the right mouse button again within the sys- 
tem’s double-click time limit. Double-clicking the right mouse button actually 
generates four events: a WM_RBUTTONDOWN and WM_RBUTTONUP 
message, the OnRButtonDbICIk call, and another WM_RBUTTONUP message 
when the button is released. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_RBUTTONDBLCLK message. 


CWnd::OnRButtonDown, CWnd::OnRButtonUp, 
WM_RBUTTONDBLCLK, CWnd::Default 
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CWnd::0nRButtonDown 


afx_msg void OnRButtonDown( UINT nFlags, CPoint point ); 


nFlags 
Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Value Description 
MK_ CONTROL Set if CONTROL Key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_SHIFT Set if SHIFT key is down. 

point 


Specifies the x- and y-coordinates of the cursor. These coordinates are always 
relative to the upper-left corner. 


Called when the user presses the right mouse button. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_RBUTTONDOWN message. 


CWnd::OnRButtonDbiClk, CWnd::OnRButtonUp, 
WM_RBUTTONDOWN, CWnd::Default 
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CWnhd::OnRButtonUp 


afx_msg void OnRButtonUp( UINT nFlags, CPoint point ); 


nFlags 
Indicates whether various virtual keys are down. This parameter can be any 
combination of the following values: 


Value Description 
MK_ CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left mouse button is down. 
MK_MBUTTON Set if middle mouse button is down. 
MK_RBUTTON Set if right mouse button is down. 
MK_ SHIFT Set if SHIFT key is down. 

point 


Specifies the x- and y-coordinates of the cursor. These coordinates are always 
relative to the upper-left corner. 


Called when the user releases the right mouse button. 
This message-handler member function calls the Default member function. 


Override this member function in your derived class to handle the 
WM_RBUTTONUP message. 


CWnd::OnRButtonDbIClk, CWnd::OnRButtonDown, WM_RBUTTONUP, 
CWnd::Default 


CWnd::0OnRenderAllFormats 


afx_msg void OnRenderAllFormats(); 


The Clipboard owner’s OnRenderAllFormats member function is called when 
the owner application is being destroyed. 


The Clipboard owner should render the data in all the formats it is capable of 
generating and pass a data handle for each format to the Clipboard by calling the 
SetClipboardData Windows function. This ensures that the Clipboard contains 
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valid data even though the application that rendered the data is destroyed. The ap- 
plication should call the OpenClipboard member function before calling the 
SetClipboardData Windows function, and call the CloseClipboard Windows 
function afterward. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_RENDERALLFORMATS message. 


::CloseClipboard, CWnd::OpenClipboard, ::SetClipboardData, 
CWnd::OnRenderFormat, WM_RENDERALLFORMATS, 
CWnd::Default 


CWnhd::OnRenderFormat 


afx_msg void OnRenderFormat( UINT nFormat ); 


nFormat 
Specifies the Clipboard format. 


The Clipboard owner’s OnRenderFormat member function is called when a par- 
ticular format with delayed rendering needs to be rendered. The receiver should 
render the data in that format and pass it to the Clipboard by calling the 
SetClipboardData Windows function. 


Do not call the OpenClipboard member function or the CloseClipboard 
Windows function from within OnRenderFormat. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_RENDERFORMAT message. 


::CloseClipboard, CWnd::OpenClipboard, ::SetClipboardData, 
WM_RENDERFORMAT, CWnd::Default 


782. CWhd::OnSetCursor 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CWnd::0OnSetCursor 


afx_msg BOOL OnSetCursor( CWnd* pWnd, UINT nHitTest, 
UINT message ); 


pWnd 
Specifies a pointer to the window that contains the cursor. The pointer may be 
temporary, and should not be stored for later use. 


nHitTest 
Specifies the hit-test area code. The hit test determines the cursor’s location. 


message 
Specifies the mouse message number. 


OnSetCursor is called if mouse input is not captured and the mouse causes cursor 
movement within the CWnd. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SETCURSOR message. 


By default, OnSetCursor calls the parent window’s OnSetCursor before pro- 
cessing. If the parent window returns TRUE, further processing is halted. Calling 
the parent window gives the parent window control over the cursor’s setting in a 
child window. 


By default, OnSetCursor also sets the cursor to an arrow if it is not in the client 
area, or to the registered-class cursor if it is. If nHitTest is HTERROR and 
message is a mouse button-down message, the MessageBeep member function is 
called. 


The message parameter is 0 when CWnd enters menu mode. 

The return value is ignored by Windows, but is used by the Default member func- 
tion when it calls the parent to determine if the parent handled the message. 
TRUE means that the message was handled; otherwise FALSE. 


CWnd::OnNcHitTest, CWnd::Default, WM_SETCURSOR 
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CWnd::0nSetFocus 


Syntax afx_msg void OnSetFocus( CWnd* pOldWnd ); 


Parameters pOldWnd 
Contains the CWnd that loses the input focus (may be NULL). The pointer 
may be temporary, and should not be stored for later use. 


Remarks Called after gaining the input focus. To display a caret, CWnd should call the ap- 
propriate caret functions at this point. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SETFOCUS message. 


See Also CWhnd::Default, WM_SETFOCUS 


CWnd::0nShowWindow 


Syntax afx_msg void OnShowWindow( BOOL bShow, UINT nStatus ); 


Parameters bShow 
Specifies whether a window is being shown. It is TRUE if the window is being 
shown; itis FALSE if the window is being hidden. 


nStatus 
Specifies the status of the window being shown. It is 0 if the message is sent be- 
cause of aShowWindow member function call; otherwise, nStatus is one of the 
following values: 


Value Description 
SW_PARENTCLOSING Parent window is closing (being made 
iconic) or a pop-up window is being hidden. 


SW_PARENTOPENING Parent window is opening (being displayed) 
or a pop-up window is being shown. 


Remarks Called when the CWnd is about to be hidden or shown. A window is hidden or 
shown when the ShowWindow member function is called, when an overlapped 
window is maximized or restored, or when an overlapped or pop-up window is 
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See Also 


Syntax 
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Remarks 


closed (made iconic) or opened (displayed on the screen). When an overlapped 
window is closed, all pop-up windows associated with that window are hidden. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SHOWWINDOW message. 


CWnd::Default, WM_SHOWWINDOW 


CWhd::0nSize 


afx_ msg void OnSize( UINT n7Type, int cx, int cy ); 


nType 
Specifies the type of resizing requested. This parameter can be one of the fol- 
lowing values: 


Value Description 

SIZEFULLSCREEN Window has been maximized. 

SIZEICONIC Window has been minimized. 

SIZENORMAL Window has been resized, but neither 
SIZEICONIC nor SIZEFULLSCREEN 
applies. 

SIZEZOOMHIDE Message is sent to all pop-up windows when 


some other window is maximized. 


SIZEZOOMSHOW Message is sent to all pop-up windows when 
some other window has been restored to its 
former size. 


CX 
Specifies the new width of the client area. 


cy 
Specifies the new height of the client area. 


Called after the size has changed. 


If the SetScrollPos or MoveWindow member function is called for a child win- 
dow from OnSize, the bRedraw parameter should be nonzero to cause the CWnd 
to be repainted. 
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This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the WM_SIZE 
message. 


CWnd::MoveWindow, CWnd::SetScrollPos, CWnd::Default, WM_ SIZE 


CWnd::0nSizeClipboard 


afx_msg void OnSizeClipboard( CWnd* pClipAppWnd, HANDLE hRect ); 


pClipApp Wnd 
Identifies the Clipboard-application window. The pointer may be temporary 
and should not be stored. 


hRect 
Identifies a handle to a global memory object. The memory object contains a 
RECT data structure that specifies the area for the Clipboard owner to paint. 


The Clipboard owner’s OnSizeClipboard member function is called by the Clip- 
board viewer when the Clipboard contains data with the CF_OWNERDISPLAY 
attribute and the size of the Clipboard-viewer window’s client area has changed. 


The OnSizeClipboard member function is called with a null rectangle (0,0,0,0) as 
the new size when the Clipboard application is about to be destroyed or min- 
imized. This permits the Clipboard owner to free its display resources. 


Within OnSizeClipboard, an application must use the GlobalLock Windows 
function to lock the memory that contains the RECT data structure. Have the ap- 
plication unlock that memory by using the GlobalUnlock Windows function 
before it yields or returns control. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SIZECLIPBOARD message. 


::GlobalLock, ::GlobalUnlock, ::SetClipboardData, 
CWnd::SetClipboard Viewer, CWnd::Default, WM_SIZECLIPBOARD 
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CWnd::OnSpoolerStatus 


Syntax afx_msg void OnSpoolerStatus( UINT nStatus, UINT nJobs ); 


Parameters nStatus 
Specifies the SP_JOBSTATUS flag. 


nJobs 
Specifies the number of jobs remaining in the Print Manager queue. 


Remarks Called from Print Manager whenever a job is added to or removed from the Print 
Manager queue. 


This call is for informational purposes only. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SPOOLERSTATUS message. 


See Also CWnd::Default, WM_SPOOLERSTATUS 


CWhd::0nSysChar 


Syntax afx_ msg void OnSysChar( UINT nChar, UINT nRepCnt, UINT nFlags ); 


Parameters nChar 
Specifies the ASCII-character key code of a Control-menu key. 
nRepCnt 


Specifies the repeat count (the number of times the keystroke is repeated as a re- 
sult of the user holding down the key). 


nFlags 
The nFlags parameter can have these values: 
Value Description 
O-7 Scan code (OEM-dependent value). Low byte of high-order 
word. 7 
8 Extended key, such as a function key or a key on the numeric 


keypad (1 if itis an extended key, 0 otherwise). 
9-10 Not used. 


Remarks 


See Also 
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Value Description 

11-12 Used internally by Windows. 

13 Context code (1 if the ALT Key is held down while the key is 
pressed, 0 otherwise). 

14 Previous key state (1 if the key is down before the message is 
sent, 0 if the key is up). 

15 Transition state (1 if the key is being released, 0 if the key is 
being pressed). 


Called 1f CWnd has the input focus and the WM_SYSKEYUP or 
WM_SYSKEYDOWN message is received. It specifies the virtual-key code of 
the Control-menu key. 


When the context code is 0, WM_SYSCHAR can pass the WM_SYSCHAR 
message to the TranslateAccelerator Windows function, which will handle it as 
though it were a normal key message instead of a system-key message. This al- 
lows accelerator keys to be used with the active window even if the active window 
does not have the input focus. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
and the right CONTROL keys on the main section of the keyboard; the INSERT, 
DELETE, HOME, END, PAGE UP, PAGE DOWN, and ARROW keys in the clusters to the 
left of the numeric keypad; and the slash (/) and ENTER keys in the numeric key- 
pad. Some other keyboards may support the extended-key bit in nFlags. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SYSCHAR message. 


:: TranslateAccelerator, WM_SYSKEYDOWN, WM_SYSKEYUP, 
CWnd::Default, WM_SYSCHAR 
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Parameters 


CWnd::OnSysColorChange 


afx_msg void OnSysColorChange(); 


Called for all top-level windows when a change is made in the system color 
setting. 


Windows calls OnSysColorChange for any window that is affected by a system 
color change. 


Applications that have brushes that use the existing system colors should delete 
those brushes and re-create them by using the new system colors. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SYSCOLORCHANGE message. 


::SetSysColors, WM_ PAINT, CWnd::Default, WM_SYSCOLORCHANGE 


CWnd::0nSysCommand 


afx_ msg void OnSysCommand( UINT n/D, LONG /Param ); 


nID 
Specifies the type of system command requested. This parameter can be one of 
the following values: 


Value Description 

SC_CLOSE Close CWnd. 

SC_HOTKEY Activate the CWnd associated with the 
application-specified hot key. 

SC_HSCROLL Scroll horizontally. 


SC_KEYMENU Retrieve a menu through a keystroke. 


Remarks 


Value 


SC_MAXIMIZE 
(or SC_ZOOM) 


SC_MINIMIZE 
(or SC_ICON) 


SC_MOUSEMENU 
SC_MOVE 
SC_NEXTWINDOW 
SC_PREVWINDOW 
SC_ RESTORE 
SC_SCREENSAVE 


SC_SIZE 
SC_TASKLIST 


SC_VSCROLL 
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Description 


Maximize CWnd. 
Minimize CWnd. 


Retrieve a menu through a mouse click. 
Move CWnd. 

Move to the next window. 

Move to the previous window. 

Checkpoint (save the previous coordinates). 


Executes the screen-save application 
specified in the Desktop section of the 
Control Panel. 


Size CWnd. 


Executes or activates the CWnd Task 
Manager application. 


Scroll vertically. 


lParam 
Contains the cursor coordinates if a Control-menu command is chosen with the 
mouse. The low-order word contains the x-coordinate, and the high-order word 
contains the y-coordinate. Otherwise, this parameter is not used. 


Called when the user selects a command from the Control menu or when the user 
selects the Maximize or Minimize button. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SYSCOMMAND message. 


By default, OnSysCommand carries out the Control-menu request for the pre- 
defined actions specified above. 


Applications that modify the Control menu must process WM_SYSCOMMAND 
messages, and aay WM_SYSCOMMAND messages not handled by the applica- 
tion must be passed on to OnSysCommand. Any command values added by an 
application must be processed by the application and cannot be passed to 
OnSysCommand. 


790 CWhd::0nSysDeadChar 


An application can carry out any system command at any time by passing a 
WM_SYSCOMMAND message to OnSysCommand. 
Access (sometimes called “accelerator’’) keystrokes that are defined to select items 


from the Control menu are translated into OnSysCommand calls; all other access 
keystrokes are translated into WM_COMMAND messages. 


See Also CWnd::Default, WM_SYSCOMMAND 


CWnd::OnSysDeadChar 


Syntax afx_msg void OnSysDeadChar( UINT nChar, UINT nRepCnt, UINT nFlags ); 
Parameters nChar 
Specifies the dead-key character value. 
nRepCnt 


Specifies the repeat count. 


nFlags 
Specifies the scan code, key-transition code, previous Key state, and context 
code, as shown in the following list: 


Value Description 

0-7 Scan code (OEM-dependent value). Low byte of high-order 
word. 

8 Extended key, such as a function key or a key on the numeric 
keypad (1 if it is an extended key, 0 otherwise). 

9-10 Not used. 

11-12 Used internally by Windows. 

13 Context code (1 if the ALT Key is held down while the key is 
pressed, 0 otherwise). 

14 Previous Key state (1 if the key is down before the call, 0 if the 
key is up). 

15 Transition state (1 if the key is being released, 0 if the key is 
being pressed). 

Remarks Called if CWnd has the input focus when the OnSysKeyUp or OnSysKeyDown 


member functions are called. It specifies the character value of a dead key. 
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This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SYSDEADCHAR message. 


CWnd::OnSysKeyDown, CWnd::OnSysKeyUp, CWnd::Default, 
WM_SYSDEADCHAR, CWnd::OnDeadChar 


CWnd::OnSysKeyDown 


afx_ msg void OnSysKeyDown( UINT nChar, UINT nRepCnt, UINT nFlags ); 


nChar 


Specifies the virtual-key code of the key being pressed. 


nRepCnt 


Specifies the repeat count. 


nFlags 


Specifies the scan code, key-transition code, previous key state, and context 
code, as shown in the following list: 


Value 


O-7 


15 


Description 


Scan code (OEM-dependent value). Low byte of high-order 
word. 


Extended key, such as a function key or a key on the numeric 
keypad (1 if it is an extended key; otherwise 0). 


Not used. 
Used internally by Windows. 


Context code (1 if the ALT key is held down while the key is 
pressed, O otherwise). 


Previous key state (1 if the key is down before the message is 
sent, 0 if the key is up). 


Transition state (1 if the key is being released, 0 if the key is 
being pressed). 


For OnSysKeyDown calls, the key-transition bit (bit 15) is 0. The context-code 
bit (bit 13) is 1 if the ALT key is down while the key is pressed; it is O if the mes- 
Sage is sent to the active window because no window has the input focus. 
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Remarks 


See Also 
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If the CWnd has the input focus, the OnSysKeyDown member function is called 
when the user holds down the ALT key and then presses another key. If no window 
currently has the input focus, the active window’s OnSysKeyDown member func- 
tion is called. The CWnd that receives the message can distinguish between these 
two contexts by checking the context code in nFlags. 


When the context code is 0, the WM_SYSKEYDOWN message received by 
OnSysKeyDown can be passed to the TranslateAccelerator Windows function, 
which will handle it as though it were a normal key message instead of a system- 
key message. This allows accelerator keys to be used with the active window even 
if the active window does not have the input focus. 


Because of auto-repeat, more than one OnSysKeyDown call may occur before the 
WM_SYSKEYUP message is received. The previous key state (bit 14) can be 
used to determine whether the OnSysKeyDown call indicates the first down transi- 
tion or a repeated down transition. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
and the right CONTROL keys on the main section of the keyboard; the INSERT, 
DELETE, HOME, END, PAGE UP, PAGE DOWN, and ARROW keys in the clusters to the 
left of the numeric keypad; and the slash (/) and ENTER keys in the numeric key- 
pad. Some other keyboards may support the extended-key bit in nFlags. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SYSKEYDOWN message. 


:: TranslateAccelerator, WM_SYSKEYUP, CWnd::Default, 
WM_SYSKEYDOWN 


CWnhd::OnSysKeyUp 
afx_msg void OnSysKeyUp( UINT nChar, UINT nRepCnt, UINT nFlags ); 


nChar 

Specifies the virtual-key code of the key being pressed. 
nRepCnt 

Specifies the repeat count. 
nFlags 


Specifies the scan code, key-transition code, previous key state, and context 
code, as shown in the following list: 


Remarks 
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Value Description 

0-7 Scan code (OEM-dependent value). Low byte of high-order 
word. 

8 Extended key, such as a function key or a key on the numeric 
keypad (1 if it is an extended key; otherwise 0). 

9-10 Not used. 

11-12 Used internally by Windows. 

13 Context code (1 if the ALT key is held down while the key is 
pressed, 0 otherwise). 

14 Previous key state (1 if the key is down before the message is 
sent, 0 if the key is up). 

15 Transition state (1 if the key is being released, 0 if the key is 
being pressed). 


For OnSysKeyUp calls, the key-transition bit (bit 15) is 1. The context-code bit 
(bit 13) is 1 if the ALT key is down while the Key is pressed; it is 0 if the mes- 
sage is sent to the active window because no window has the input focus. 


If the CWnd has the focus, the OnSysKeyUp member function is called when the 
user releases a key that was pressed while the ALT key was held down. If no win- 
dow currently has the input focus, the active window’s OnSysKeyUp member 
function is called. The CWnd that receives the call can distinguish between these 
two contexts by checking the context code in nFlags. 


When the context code is 0, the WM_SYSKEYUP message received by 
OnSysKeyUp can be passed to the TranslateAccelerator Windows function, 
which will handle it as though it were a normal key message instead of a system- 
key message. This allows accelerator keys to be used with the active window even 
if the active window does not have the input focus. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT 
and the right CONTROL Keys on the main section of the keyboard; the INSERT, 
DELETE, HOME, END, PAGE UP, PAGE DOWN, and ARROW keys in the clusters to the 
left of the numeric keypad; and the slash (/) and ENTER keys in the numeric key- 
pad. Some other keyboards may support the extended-key bit in nFlags. 
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For non-USA Enhanced 102-key keyboards, the right ALT key is handled as a CON- 
TROL-ALT key. The following shows the sequence of messages and calls that result 
when the user presses and releases this key: 


Sequence Function accessed Message passed 
1. WM_KEYDOWN VK_CONTROL 
2. WM_KEYDOWN VK_MENU 

3, WM_KEYUP VK_CONTROL 
4 WM_SYSKEYUP VK_MENU 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_SYSKEYUP message. 


:: TranslateAccelerator, WM_SYSKEYDOWN, CWnd::Default, 
WM_SYSKEYUP 


CWhd::OnTimeChange 


afx_msg void OnTimeChange(); 


Called after the system time is changed. 


Have any application that changes the system time send this message to all top- 
level windows. To send the WM_TIMECHANGE message to all top-level win- 
dows, an application can use the SendMessage Windows function with the hWnd 
parameter set to OXFFFF. 


This message-handler member function calls the Default member function. 


Override this member function in your derived class to handle the 
WM_TIMECHANGE message. 


::SendMessage, CWnd::Default, WM_TIMECHANGE 
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CWnd::OnTimer 


afx_msg void OnTimer( UINT n/DEvent ); 


nlDEvent 
Specifies the identifier of the timer. 


Called after each interval specified in the SetTimer member function used to in- 
stall a timer. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the WM_ TIMER 
message. 


CWnd::SetTimer, WM_TIMER, CWnd::Default 


CWnd::0nVKeyToltem 
afx_msg int OnVKeyTolItem( UINT nKey, CWnd* pListBox, UINT nindex ); 


nKey 
Specifies the virtual-key code of the key that the user pressed. 


pListBox 
Specifies a pointer to the list box. The pointer may be temporary. 


nlndex 
Specifies the current caret position. 


If the CWnd owns a list box with the LBS_WANTKEYBOARDINPUT style, 
the list box will send the WM_VKEYTOITEM message in response to a 
WM_KEYDOWN message. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_VKEYTOITEM message. 
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Return Value 


See Also 


Syntax 


Parameters 


Specifies the action that the application performed in response to the message. A 
return value of —2 indicates that the application handled all aspects of selecting the 
item and wants no further action by the list box. A return value of —1 indicates that 
the list box should perform the default action in response to the keystroke. A re- 
turn value of 0 or greater specifies the index of an item in the list box and indicates 
that the list box should perform the default action for the keystroke on the given 
item. 


WM_KEYDOWN, WM_VKEYTOITEM, CWnd::Default 


CWnhd::0OnVScroll 


afx_msg void OnVScroll( UINT nSBCode, UINT nPos, CWnd* pScrollBar ); 


nSBCode 
Contains a scroll-bar code that specifies the user’s scrolling request. This para- 
meter can be one of the following values: 


Value Description 

SB_ BOTTOM Scroll to bottom. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_ LINEUP Scroll one line up. 
SB_ PAGEDOWN Scroll one page down. 
SB_PAGEUP Scroll one page up. 


SB_THUMBPOSITION Scroll to the absolute position. The current 
position is provided in nPos. 


SB_THUMBTRACK Drag scroll box to specified position. The 
current position is provided in nPos. 
SB_ TOP Scroll to top. 
nPos 


Contains the scroll-box position if the scroll-bar code is 
SB_ THUMBPOSITION; otherwise, not used. 


Remarks 
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pScrollBar 
If the message is sent by a scroll-bar control, pScrollBar identifies the control. 
If the message is sent as a result of the user clicking a pop-up window’s scroll 
bar, pScrollBar is not used. The pointer may be temporary. 


Called when the user clicks a vertical scroll bar. 


OnVScroll typically is used by applications that give some feedback while the 
scroll box is being dragged. 


If OnVScroll scrolls the contents of CWnd, it must also reset the position of the 
scroll box by using the SetScrollPos member function. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_VSCROLL message. 


CWnad::SetScrollPos, CWnd::OnHScroll, WM_VSCROLL, CWnd::Default 


CWnhd::0nVScrollClipboard 


afx_ msg void OnVScrollClipboard( CWnd* pClipApp Wnd, UINT nSBCode, 
UINT nPos ); 


pClipApp Wnd 
Specifies a pointer to a Clipboard-viewer window. The pointer may be tem- 
porary. 


nSBCode 
Specifies one of the following scroll-bar codes: 


Value Description 

SB_ BOTTOM Scroll to lower right. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_LINEUP Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 


SB_PAGEUP Scroll one page up. 
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Value Description 


SB_THUMBPOSITION Scroll to the absolute position. The current 
position is provided in nPos. 


SB_ TOP Scroll to upper left. 


nPos 
Contains the scroll box position if the scroll-bar code is 
SB_THUMBPOSITION,; otherwise, nPos is not used. 


If the CWnd owns the Clipboard, the OnVScrollClipboard member function is 
called by the Clipboard viewer when the Clipboard data has the 
CF_OQWNERDISPLAY format and there is an event in the Clipboard viewer’s 
vertical scroll bar. OnVScrollClipboard should scroll the Clipboard image, invali- 
date the appropriate section, and update the scroll-bar values. 


The Clipboard owner should use the Invalidate or InvalidateRect member func- 
tion or repaint as desired. The scroll-bar position should also be reset. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_VSCROLLCLIPBOARD message. 


CWnd::Invalidate, CWnd: :OnHScrollClipboard, CWnd::InvalidateRect, 
WM_VSCROLLCLIPBOARD, CWnd::Default 


CWnhd::OnWininiChange 


afx_msg void OnWinIniChange( LPSTR /pSection ); 


[pSection 
Points to a string that specifies the name of the section that has changed (the 
string does not include the square brackets). 


Called after a change has been made to the Windows initialization file, WIN.INI. 


To send the WM_WININICHANGE message to all top-level windows, an appli- 
cation can use the SendMessage Windows function with the )Wnd parameter set 
to OXFFFF. 


If an application changes many different sections in WIN.INI at the same time, the 
application should send one WM_ WININICHANGE message with /pSection set 
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to NULL. Otherwise, an application should send WM_WININICHANGE each 
time it makes a change to WIN.INI. 


If an application receives an OnWinIniChange call with /pSection set to NULL, 
the application should check all sections in WIN.INI that affect the application. 


This message-handler member function calls the Default member function. 
Override this member function in your derived class to handle the 
WM_ WININICHANGE message. 


::SendMessage, ::SystemParametersInfo, WM_WININICHANGE, 
CWnd::Default 


CWnd::OpenClipboard 


BOOL OpenClipboard(); 


Opens the Clipboard. Other applications will not be able to modify the Clipboard 
until the CloseClipboard Windows function is called. 


The current CWnd object will not become the owner of the Clipboard until the 
EmptyClipboard Windows function is called. 


TRUE if the Clipboard is opened via CWnd, or FALSE if another application or 
window has the Clipboard opened. 


::CloseClipboard, ::EmptyClipboard, ::OpenClipboard 


800 CWnd::Openicon 
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CWnd::Openicon 


BOOL Openlcon(); 


Activates and displays a minimized (iconic) window. Windows restores the win- 
dow to its original size and position. 


TRUE if the function is successful; otherwise FALSE. 


:;Openicon, CWnd::CloseWindow 


CWnd::PostMessage 


BOOL PostMessage( UINT message, UINT wParam = 0, LONG [Param = 0 ); 


message 
Specifies the message to be posted. 


wParam 
Specifies additional message information. The content of this parameter de- 
pends on the message being posted. 


[Param 
Specifies additional message information. The content of this parameter de- 
pends on the message being posted. 


Places a message in the current CWnd object’s message queue, and then returns 
without waiting for the corresponding window to process the message. Messages 
in a message queue are retrieved by calls to the GetMessage or PeekMessage 
Windows functions. 


An application should never use the PostMessage member function to send a mes- 
sage to a control; it should use SendDlgItemMessage. 


The Windows PostMessage function can be used to access another application. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 
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TRUE if the message is posted; otherwise FALSE. 


::GetMessage, ::PeekMessage, ::PostMessage, ::PostAppMessage, 
CWnd::SendMessage, CWnd::SendDlgItemMessage 


CWnd::PreTranslateMessage 


Protected: 
virtual BOOL PreTranslateMessage( MSG* pMszg ); 


pMsg 
Points to a MSG structure that contains the message to process. 


Used by class CWinApp to translate window messages before they are dispatched 
by the DispatchMessage Windows function. 


TRUE if the message is translated and should not be dispatched; FALSE if the 
message was not translated and should be dispatched. 


:: TranslateMessage, ::IsDialogMessage, CWinApp::PreTranslateMessage 


CWnd::ReleaseDC 


int ReleaseDC( CDC* pDC ); 


pDC 
Identifies the device context to be released. 


Releases a device context, freeing it for use by other applications. The effect of the 
ReleaseDC member function depends on the device-context type. It only frees 
common and window device contexts. It has no effect on class or private device 
contexts. 


802 CWnd::ScreenToClient 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


The application must call the ReleaseDC member function for each call to the 
GetWindowDC member function and for each call to the GetDC member func- 
tion that retrieves a common device context. 


Specifies whether the device context is released. It is 1 if the device context is re- 
leased; otherwise 0. 


CWnd::GetDC, CWnd::GetWindowDC, ::ReleaseDC 


CWhd::ScreentoClient 


void ScreenToClient( LPPOINT /pPoint ) const; 


void ScreenToClient( LPRECT /pRect ) const; 


lpPoint 
Points to a CPoint or POINT structure that contains the screen coordinates to 
be converted. 


[pRect 
Points to a CRect or RECT structure that contains the screen coordinates to be 
converted. 


Converts the screen coordinates of a given point or rect on the display to client 
coordinates. 


The ScreenToClient member function uses CWnd and the screen coordinates 
given in /pPoint or lpRect to compute client coordinates, and then replaces the 
screen coordinates with the client coordinates. The new coordinates are relative to 
the upper-left corner of the CWnd client area. 


The ScreenToClient formula assumes the given point is in screen coordinates. 


CWnd::ClientToScreen ::ScreenToClient 


Syntax 


Parameters 


Remarks 
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CWnd::ScrollWindow 


void ScrollWindow( int xAmount, int yAmount, LPRECT /pRect = NULL, 
LPRECT /pClipRect = NULL ); 


xAmount 
Specifies the amount (in device units) to scroll in the x-axis direction. 


yAmount 
Specifies the amount (in device units) to scroll in the y-axis direction. 


[pRect 
Points to a CRect or RECT structure that specifies the portion of the client area 
to be scrolled. If JpRect is NULL, the entire client area is scrolled. 


[pClipRect 
Points to a CRect or RECT structure that specifies the clipping rectangle to be 
scrolled. Only bits inside this rectangle are scrolled. If IpClipRect is NULL, the 
entire window is scrolled. 


Scrolls the current CWnd object by moving the contents of the window’s client 
area the number of units specified by xAmount along the screen’s x-axis and the 
number of units specified by yAmount along the y-axis. The scroll moves right if 
xAmount is positive and left if it is negative. The scroll moves down if yAmount is 
positive and up if it is negative. 


If the caret is in the CWnd being scrolled, ScrollWindow automatically hides the 
caret to prevent it from being erased, then restores the caret after the scroll is 
finished. The caret position is adjusted accordingly. 


The area uncovered by the ScrollWindow member function is not repainted, but is 
combined into the current CWnd object’s update region. The WM_ PAINT mes- 
sage will be sent, notifying it that the region needs repainting. To repaint the un- 
covered area at the same time the scrolling is done, call the UpdateWindow 
member function immediately after calling ScrollWindow. | 


If IpRect is NULL, the positions of any child windows in the window are offset by 
the amount specified by xAmount and yAmount, and any invalid (unpainted) areas 
in the CWnd are also offset. ScrollWindow is faster when [pRect is NULL. 
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See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


If JpRect is not NULL, the positions of child windows are not changed, and in- 
valid areas in CWnd are not offset. To prevent updating problems when [pRect is 
not NULL, call the UpdateWindow member function to repaint CWnd before 
calling Scroll Window. 


CWnd:: Update Window, ::ScrollWindow 


CWhd::SendDigltemMessage 


LONG SendDligItemMessage( int n/D, UINT message, UINT wParam = 0, 
LONG [Param = 0 ); 


nID 
Specifies the integer identifier of the dialog item that is to receive the message. 


message 
Specifies the message value. 


wParam 
Specifies additional message information. The content of this parameter de- 
pends on the message being sent. 


[Param 
Specifies additional message information. The content of this parameter de- 
pends on the message being sent. 


Sends a message to the specified control. 


The SendDlgItemMessage member function does not return until the message has 
been processed. 


Using SendDlgItemMessage is identical to obtaining a CWnd* to the given con- 
trol and calling the SendMessage member function. 


Specifies the value returned by the control’s window procedure, or 0 if the control 
identifier is not valid. 


CWnd::SendMessage, ::SendDigItemMessage 


syntax 


Parameters 


Remarks 


Return Value 


See Also 


syntax 


Remarks 


CWnd::SetActiveWindow 805 


CWnd::SendMessage 
LONG SendMessage( UINT message, UINT wParam = 0, LONG [Param = 0 ); 


message 
Specifies the message to be sent. 


wParam 
Specifies additional message information. The content of this parameter de- 
pends on the message being sent. 


[Param 
Specifies additional message information. The content of this parameter de- 
pends on the message being sent. 


Sends a message to a window or windows. The SendMessage member function 
calls the window procedure for the current CWnd object and does not return until 
that window procedure has processed the message. This is in contrast to the 
PostMessage member function which places the message into the CWnd message 
queue and returns immediately. 


The result returned by the invoked window procedure; its value depends on the 
message being sent. 


::InSendMessage, CWnd::PostMessage, CWnd::SendDigitemMessage, 
::SendMessage 


CWnd::SetActiveWindow 


CWnd* SetActiveWindow(); 


Makes CWnd the active window. 


The SetActiveWindow member function should be used with care since it 
allows an application to arbitrarily take over the active window and input focus. 
Normally, Windows takes care of all activation. 
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| Return Value 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


The identity of the window that was previously active. 


The returned pointer may be temporary, and should not be stored. 


::SetActiveWindow, CWnd::GetActiveWindow 


CWnd::SetCapture 


CWhnd* SetCapture(Q); 


Causes all subsequent mouse input to be sent to the current CWnd object, regard- 
less of the position of the cursor. 


When CWnd no longer requires all mouse input, the application should call the 
ReleaseCapture Windows function so that other windows can receive mouse 
input. 

A pointer to the window object that previously received all mouse input. It is 


NULL if there is no such window. The returned pointer may be temporary, and 
should not be stored. | | 


::ReleaseCapture, ::SetCapture, CWnd::GetCapture 


CWnd::SetCaretPos 


static void SetCaretPos( POINT point ); 


point 
Specifies the new logical x- and y-coordinates of the caret. 


Moves the caret to the position given by logical coordinates specified by point. 
Logical coordinates are relative to the client area and are affected by the mapping 
mode, so the exact position in pixels depends on this mapping mode. 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


CWnd::SetClipboardViewer — 807 


The SetCaretPos member function moves the caret only if it is owned by a win- 
dow in the current task. SetCaretPos moves the caret whether or not the caret is 
hidden. 


The caret is a shared resource. A CWnd should not move the caret if it does not 
own the caret. 


CWnd::GetCaretPos, ::SetCaretPos 


CWnhd::SetClipboardViewer 


HWND SetClipboard Viewer(); 


Adds CWnd to the Clipboard-viewer chain and returns a handle to the next win- 
dow in the chain. 


A CWhnd that is part of the Clipboard-viewer chain must respond to 
WM_DRAWCLIPBOARD, WM_CHANGECBCHAIN, and 
WM_DESTROY messages, and pass the message to the next window in the 
chain. 


This member function sends a WM_DRAWCLIPBOARD message to the 
CWnd. Since the handle to the next window in the Clipboard-viewer chain has 
not yet been returned, the application should be careful to not pass on the 
WM_DRAWCLIPBOARD message that it receives during the call to 
SetClipboard Viewer. 


If an application wishes to remove itself from the Clipboard-viewer chain, it must 
call the ChangeClipboardChain member function. 


A handle to the next window in the Clipboard-viewer chain. This handle should be 
saved in static memory and used to pass on Clipboard-viewer chain messages. 


CWnd::ChangeClipboardChain, ::SetClipboard Viewer 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


CWnd::SetDigitemint 


void SetDigItemInt( int n/D, UINT nValue, BOOL bSigned = TRUE ); 


nID 
Specifies the integer ID of the control to be modified. 


nValue 
Specifies the value to be set. 


bSigned 
Specifies whether or not the integer value is signed. 


Sets the text of a control to the string that represents the integer value given by 
nValue. The SetDigItemInt member function converts nValue to a string that con- 
sists of decimal digits, and then copies the string to the control. 


If bSigned is TRUE, nValue is assumed to be signed. If nValue is signed and less 
than 0, the function places a minus sign before the first digit in the string. 


CWnd::GetDigItemInt, ::SetDigItemInt, WM_SETTEXT 


CWnd::SetDigitem Text 


void SetDigItemText( int n/D, const char FAR®* /pString ); 


nID 
Specifies the integer ID of the control whose text is to be set. 


lpString | 
Points to a CString or null-terminated string that is to be copied to the control. 


Sets the caption or text of a control owned by CWnd. 


::SetDigItemText, WM_SETTEXT, CWnd::GetDigItemText 


CWnd::SetFont 809 


CWnd::SetFocus 


Syntax CWnd* SetFocus(); 


Remarks Claims the input focus. The input focus directs all subsequent keyboard input to 
CWnd. The window, if any, that previously had the input focus loses it. 


The SetFocus member function sends a WM_KILLFOCUS message to the 
CWnd that loses the input focus and a WM_SETFOCUS message to the CWnd 
that receives the input focus. It also activates either the CWnd or its parent. 


If the current CWnd is active but doesn’t have the focus (that 1s, no window has 
the focus), any key pressed will produce the messages WM_SYSCHAR, 
WM_SYSKEYDOWN, or WM_SYSKEYUP. 


Return Value A pointer to the window object that previously had the input focus. It is NULL if 
there is no such window. The returned pointer may be temporary and should not 
be stored. 

See Also ::SetFocus, CWnd::GetFocus 


CWnd::SetFont 


Syntax void SetFont(CFont* pF ont, BOOL bRedraw = TRUE); 


Parameters pFont 
Specifies the new font. 


bRedraw 
If TRUE, redraw the CWnd; otherwise FALSE. 


Remarks Sets the CWnd current font to CFont. If bRedraw is TRUE, CWnd will also be 
redrawn. 


See Also CWnd::GetFont, WM_SETFONT 
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Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


CWnd::SetMenu 


BOOL SetMenu( CMenu* pMenu ); 
pMenu 
Identifies the new menu. If this parameter is NULL, the current menu is 


removed. 


Sets the current menu to the specified menu. 


SetMenu will not destroy a previous menu. An application should call the 
CMenu::DestroyMenu member function to accomplish this task. 


TRUE if the menu is changed; otherwise FALSE. 


CMenu::DestroyMenu, CMenu::LoadMenu, ::SetMenu, CWnd::GetMenu 


CWnd::SetParent 


CWnd* SetParent( CWnd* pWndNewParent ); 


pWndNewParent 
Identifies the new parent window. 


Changes the parent window of a child window. 


If the CWnd is visible, Windows performs the appropriate redrawing and 
repainting. 


A pointer to the previous parent window object. The returned pointer may be 
temporary. 


::SetParent, CWnd::GetParent 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


CWnd::SetScrollPos 811 


CWnd::SetRedraw 


void SetRedraw( BOOL bRedraw = TRUE ); 


bRedraw 
Specifies the state of the redraw flag. If this parameter is TRUE, the redraw 
flag is set; if FALSE, the flag is cleared. 


An application calls SetRedraw to allow changes to be redrawn, or to prevent 
changes from being redrawn. 


This member function sets or clears the redraw flag. While the redraw flag is 
cleared, the contents will not be updated after each change, and will not be re- 
painted until the redraw flag is set. For example, an application that needs to add 
several items to a list box can clear the redraw flag, add the items, then set the re- 
draw flag. Finally, the application can call the Invalidate or InvalidateRect mem- 
ber function to cause the list box to be repainted. 


WM_SETREDRAW 


CWnd::SetScrollPos 


int SetScrollPos( int nBar, int nPos, BOOL bRedraw = TRUE ); 


nBar 
Specifies the scroll bar to be set. It can be one of the following values: 


Value Meaning 


SB_ CTL Sets the position of a scroll-bar control. In this case, the 
CWnd must be a scroll-bar control. 


SB_HORZ Sets the CWnd horizontal scroll-bar position. 
SB_ VERT Sets the CWnd vertical scroll-bar position. 


nPos 
Specifies the new position. It must be within the scrolling range. 


bRedraw 
Specifies whether the scroll bar should be redrawn to reflect the new position. 
If bRedraw is TRUE, the scroll bar is redrawn; if FALSE, it is not redrawn. 
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Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Sets the current position of a scroll box to that specified by nPos and, if specified, 
redraws the scroll bar to reflect the new position. 


Setting bRedraw to FALSE is useful whenever the scroll bar will be redrawn by a 
subsequent call to another function. 


The previous position of the scroll box. 


::SetScrollPos, CWnd::GetScrollPos 


CWhd::SetScrollRange 


void SetScrollRange( int nBar, int nMinPos, int nMaxPos, 
BOOL bRedraw = TRUE ); 


nBar 
Specifies the scroll bar to be set. It can be one of the following values: 


Value Meaning 


SB_CTL Sets the position of a scroll-bar control. In this case, the 
CWhnd must be a scroll-bar control. 


SB_HORZ Sets the CWnd horizontal scroll-bar position. 
SB_ VERT Sets the CWnd vertical scroll-bar position. 


nMinPos 
Specifies the minimum scrolling position. 


nMaxPos 
Specifies the maximum scrolling position. 


bRedraw 
Specifies whether or not the scroll bar should be redrawn to reflect the change. 
If bRedraw is TRUE, the scroll bar is redrawn; if FALSE, it is not redrawn. 


Sets minimum and maximum position values for the given scroll bar. It can also 
be used to hide or show standard scroll bars by setting nMinPos and nMaxPos to 0. 


An application should not call this function to hide a scroll bar while processing a 
scroll-bar notification message. 


See Also 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


CWnd::SetTimer 813 


If SetScrollRange immediately follows the SetScrollPos member function, the 
bRedraw parameter in the SetScrollPos member function should be set to FALSE 
to prevent the scroll bar from being drawn twice. 


The difference between the values specified by nMinPos and nMaxPos must not 
be greater than 32,767. 


CWnd::SetScrollPos, ::SetScrollRange, CWnd::GetScrollRange 


CWnhd::SetSysModalWindow 


CWnd* SetSysModalWindow(); 


Makes the CWnd a system-modal window. 


If another window is made the active window (for example, the system-modal win- 
dow creates a dialog box that becomes the active window), the active window be- 
comes the system-modal window. When the original window becomes active 
again, it is system modal. To end the system-modal state, destroy the system- 
modal window. 


A pointer to the window object that was previously the system-modal window. 
The returned pointer may be temporary. 


::SetSysModalWindow, CWnd::GetSysModalWindow 


CWnd::SetTimer 


UINT SetTimer( int n/DEvent, UINT nElapse, 
UINT (FAR PASCAL EXPORT* [pfnTimer)(QHWND, UINT, int, DWORD) ); 


nlDEvent 
Specifies a nonzero timer identifier. 


nElapse 
Specifies the time-out value, in milliseconds. 
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Remarks 


Return Value 


See Also 


Syntax 


Parameters 


lpfnTimer 
Specifies the address of the application-supplied TimerProc callback function 
that processes the WM_ TIMER messages. If this parameter is NULL, the 
WM_TIMER messages are handled by the CWnd. 


Installs a system timer. A time-out value is specified, and every time a time-out oc- 
curs, the system posts a WM_ TIMER message to the installing application’s mes- 
Sage queue or passes the message to an application-supplied TimerProc callback 
function. 


Timers are a limited global resource; therefore, it is important that an application 
check the value returned by the SetTimer member function to verify that a timer 
is actually available. 


The [pfnTimer callback function need not be named TimerProc, but it must be de- 
fined as follows, and return 0. 


UINT FAR PASCAL EXPORT TimerProc( 


HWND hWnd, //handle of CWnd that called SetTimer 
UINT nMsg, . //WM_TIMER 

int nIDEvent //timer identification 

DWORD dwTlime //system time 


ee 
The timer identifier to use in KillTimer if the function is successful; otherwise 0. 


WM_TIMER, CWnad::KillTimer, ::SetTimer, CWnd::FromHandle 


CWhd::SetWindowPos 


void SetWindowPos( const CWnd* pWndInsertAfter, int x, int y, int cx, int cy, 
UINT nFlags ); 


pWhndInsertAfter 
Identifies a CWnd in the window-manager’s list that will precede the posi- 
tioned window. 


x 
Specifies the x-coordinate of the new upper-left corner. 


Remarks 


CWnd::SetWindowPos 815 


Specifies the y-coordinate of the new upper-left corner. 


CX 
Specifies the new window’s width. 


cy 
Specifies the new window’s height. 


nFlags 
Specifies sizing and positioning options. It can be a combination of the follow- 
ing values: 


Value Meaning 


SWP_DRAWFRAME Draws a frame (defined in the CWnd class 
description) around the window. 


SWP_HIDEWINDOW Hides the CWnd. 


SWP_NOACTIVATE Does not activate the CWnd. 
SWP_NOMOVE Retains current position (ignores the x and y 
parameters). 

SWP_NOREDRAW Does not redraw changes. 

SWP_NOSIZE Retains current size (ignores the cx and cy 
parameters). 

SWP_NOZORDER Retains current ordering (ignores 
pWndInsertAfter). 


SWP_SHOWWINDOW Displays the CWnd. 


Changes the size, position, and ordering of child, pop-up, and top-level windows. 
Child, pop-up, and top-level windows are ordered according to their appearance 
on the screen; the topmost window receives the highest rank, and it is the first win- 
dow in the list. This ordering is recorded in a window list. 


If the SWP_NOACTIVATE flag is not specified, the pWndInsertAfter parameter 
is ignored and CWnd is activated and placed at the top of the Z order, in front of 
any other windows. 


If the SWP_NOZORDER flag is not specified, Windows places CWnd in the 
position following the window identified by pWndInsertAfter. If pWndInsertAfter 
is &wndTop, Windows places CWnd at the top of the list. If pWndInsertAfter is 
set to &wndBottom, Windows places CWnd at the bottom of the list. 


816 CWnd::SetWindowText 


If the SWP_SHOWWINDOW or the SWP_HIDEWINDOW flag is set, CWnd 
cannot be moved or sized. 


All coordinates for child windows are relative to the upper-left corner of the parent 
window’s client area. 


See Also ::DeferWindowsPos, ::SetWindowPos 


CWnd::SetWindowText 


Syntax void SetWindowText( const char FAR* /pString ); 


Parameters lpString 
Points to a CString or null-terminated string. 


Remarks Sets the caption title (if one exists) to the specified text. If the CWnd is a control, 
the SetWindowText member function sets the text within the control instead of 
within the caption. This function sends a WM_SETTEXT message to CWnd. 


See Also CWnd::GetWindowText, ::SetWindowText 


CWnd::ShowCaret 


Syntax void ShowCaret(); 


Remarks Shows the caret on the display at the caret’s current position. Once shown, the 
caret begins flashing automatically. 


The ShowCaret member function shows the caret only if it has a current shape 
and has not been hidden two or more times in a row. If the caret is not owned by 
CWnd, the caret is not shown. 


Hiding the caret is accumulative. If the HideCaret member function has been | 
called five times in a row, ShowCaret must be called five times to show the caret. 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


CWnd::ShowScrollBar 817 


The caret is a shared resource. The CWnd should show the caret only when it has 
the input focus or is active. 


CWnd::HideCaret, ::ShowCaret 


CWnd::ShowOwnedPopups 
void ShowOwnedPopups( BOOL bShow = TRUE ); 
bShow 
Specifies whether pop-up windows are hidden. It is TRUE if all hidden pop-up 


windows should be shown; it is FALSE if all visible pop-up windows should 
be hidden. 


Shows or hides all pop-up windows associated with the current CWnd object. 


::ShowOwnedPopups 


CWnd::ShowScrollBar 


void ShowScrollBar( UINT nBar, BOOL bShow = TRUE ); 


nBar 
Specifies whether the scroll bar is a control or part of a window’s nonclient 
area. If it is part of the nonclient area, nBar also indicates whether the scroll bar 
is positioned horizontally, vertically, or both. It must be one of the following 
values: 


Value Meaning 

SB_ BOTH Specifies the CWnd’s horizontal and vertical scroll bars. 
SB_CTL Specifies that the CWnd is a scroll-bar control. 
SB_HORZ Specifies the CWnd’s horizontal scroll bar. 


SB_ VERT Specifies the CWnd’s vertical scroll bar. 
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Remarks 


See Also 


Syntax 


Parameters 


bShow 


Specifies whether or not Windows hides the scroll bar. If bShow is FALSE, the 
scroll bar is hidden. Otherwise, the scroll bar is displayed. 


Displays or hides a scroll bar, depending on the value of bShow. If bShow is 
TRUE, the scroll bar is displayed; if FALSE, the scroll bar is hidden. 


::ShowScrollBar 


CWnhd::ShowWindow 


BOOL ShowWindow( int nCmdShow ); 


nCmdShow 


Specifies how the CWnd is to be shown. It must be one of the following values: 


Value 
SW_HIDE 


Meaning 


Hides CWnd and passes activation to 


SW_MINIMIZE 
SW_RESTORE 
SW_SHOW 
SW_SHOWMAXIMIZED 
SW_SHOWMINIMIZED 


SW_SHOWMINNOACTIVE 


SW_SHOWNA 


another window. 


Minimizes CWnd and activates the 
top-level window in the window- 
manager’s list. 


Same as SW_SHOWNORMAL. 


Activates CWnd and displays it in its 
current size and position. 


Activates CWnd and displays it as a 
maximized window. 


Activates CWnd and displays it as a 
minimized (iconic) window. 


Displays CWnd as minimized (iconic) 
window. The window that is currently 
active remains active. 


Displays CWnd in its current state. 
The window that is currently active 
remains active. 


Remarks 


Return Value 


See Also 


syntax 


Remarks 


See Also 
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Value Meaning 


SW_SHOWNOACTIVATE Displays CWnd in its most recent size 
| and position. The window that is 
currently active remains active. 


SW_SHOWNORMAL Activates and displays CWnd. If 
CWhnd is minimized or maximized, 
Windows restores it to its original size 
and position. 


Displays or removes the CWnd., as specified by nCmdShow. 
ShowWindow must be called only once per program with 


CWinApp::m_nCmdShow. Subsequent calls to ShowWindow must use one of 
the values listed above, instead of the one specified by m_nCmdShow. 


Specifies the previous state of the CWnd. It is TRUE if the CWnd was pre- 
viously visible; FALSE if the CWnd was previously hidden. 


::Show Window 


CWnhd::UpdateWindow 


void Update Window(); 


Updates the client area by sending a WM_ PAINT message if the update region is 
not empty. The UpdateWindow member function sends a WM_ PAINT message 
directly, bypassing the application queue. If the update region is empty, 

WM_ PAINT is not sent. 


:; UpdateWindow 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


CWnd::ValidateRect 


void ValidateRect( LPRECT /pRect ); 


lpRect 
Points to a CRect or RECT structure that contains the rectangle (in client 
coordinates) to be removed from the update region. 


Validates the client area within the given rectangle by removing the rectangle from 
the update region of the given window. If [pRectis NULL, the entire window is 
validated. 


The BeginPaint member function automatically validates the entire client area. 
Neither the ValidateRect nor ValidateRgn member function should be called if a 
portion of the update region needs to be validated before WM_PAINT is next 
sent. 


Windows continues to send WM_PAINT messages until the current update re- 
gion is validated. 


CWnd::BeginPaint, :: ValidateRect, CWnd:: ValidateRgn 


CWnd::ValidateRgn 


void ValidateRgn( CRgn* pRen ); 


pRgn 7 
Identifies a region that defines the area to be removed from the update region. 


Validates the client area within the given region by removing the region from the 
current update region of the given window. If pRgn is NULL, the entire window is 
validated. 


The given region must have been created previously by a region function. The re- 
gion coordinates are assumed to be client coordinates. 


:: ValidateRgn 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 
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Remarks 


Return Value 
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CWnhd::WindowFromPoint 


static CWnd* WindowFromPoint( POINT point ); 


point 
Specifies a CPoint or POINT data structure that defines the point to be 
checked. 


Identifies the window that contains the given point; point must specify the screen 
coordinates of a point on the screen. 


A pointer to the window object in which the point lies. It is NULL if no window 
exists at the given point. The returned pointer may be temporary. 


::WindowFromPoint, CWnd::ChildWindowFromPoint 


CWnd::WindowProc 


protected: virtual LONG WindowProc( UINT message, UINT wParam, 
LONG [Param ); 


message 
Specifies the Windows message to be processed. 


wParam 
Provides additional information used in processing the message. The parameter 
value depends on the message. 


lParam 
Provides additional information used in processing the message. The parameter 
value depends on the message. 


Provides a Windows procedure (WindowProc) for a CWnd object. It dispatches 
messages through the window’s message map. 


The return value depends on the message. 


822 


CWnd::m_ hWnd 


Data Members 


Remarks 


See Also 


Remarks 


See Also 


Remarks 


See Also 


CWnd::m_ hWnd 


The handle of the Windows window attached to this CWnd. The m_ hWnd data 
member is a public variable of type HWND. 


CWhnd::Attach, CWnd::Detach, CWnd::FromHandle 


CWnhd::wndBottom 


This is a special static CWnd that has an HWND of 1. It is only used with the 
pWndInsertAfter parameter of the SetWindowPos member function to indicate 
that the CWnd being operated on should be moved to the bottom of the window 
list. wndBottom is a public variable of type static const CWnd. 


CWnd::SetWindowPos 


CWhd::wndTop 


This is a special static CWnd that has an HWND of 0. It is only used with the 
pWndInsertAfter parameter of the SetWindowPos member function to indicate 
that the CWnd being operated on should be moved to the top of the window list. 
wndTop is a public variable of type static const CWnd. 


CWnd::SetWindowPos 


CWordArray _—823 


class CWordArray : public CObject 


Public Members 


The CWordArray class supports arrays of 16-bit 
words. 


The member functions of CWordArray are similar 
to the member functions of class CObArray. Be- 
cause of this similarity, you can use the CObArray reference documentation for 
member function specifics. Wherever you see a CObject pointer as a function 
parameter or return value, substitute a WORD. 


CObject* CObArray::GetAt( int <nIndex> ) const; 


for example, translates to 


WORD CWordArray::GetAt( int <nIndex> ) const; 


CWordArray incorporates the IMPLEMENT_SERIAL macro to support serial- 
ization and dumping of its elements. If an array of words is stored to an archive, 
either with the overloaded insertion operator or with the Serialize member func- 
tion, each element is, in turn, serialized. 


If you need a dump of individual elements in the array, you must set the depth of 
the dump context to 1 or greater. 


#include <afxcoll.h> 


Construction/Destruction 


CWordArray Constructs an empty array for words. 
~CWordArray Destroys a CWordArray object. 

Bounds 

GetSize Gets number of elements in this array. 
GetUpperBound Returns the largest valid index. 

SetSize Sets the number of elements to be contained in this 


array. 


CWordArray 


Operations 
FreeExtra 


RemoveAll 


Element Access 
GetAt 
SetAt 


ElementAt 


Growing the Array 
SetAtGrow 


Add 


Insertion/Removal 
InsertAt 


RemoveAt 


Operators 
operator [ | 


Frees all unused memory above the current upper 
bound. 


Removes all the elements from this array. 


Returns the value at a given index. 


Sets the value for a given index; array not allowed 
to grow. 


Returns a temporary reference to the element 
pointer within the array. 


Sets the value for a given index, growing the array 
if necessary. 


Adds an element to the end of the array; grows the 
array if necessary. 


Inserts an element (or all the elements in another 
array) at a specified index. 


Removes an element at a specific index. 


Sets or gets the element at the specified index. 


EE: 


iostream Class List 


iostream Class List 829 


Abstract Stream Base Class 


ios 


Input Stream Classes 


istream 


ifstream 
istream_ withassign 


istrstream 


Output Stream Classes 
ostream 


ofstream 
ostream_ withassign 


ostrstream 


Stream base class. 


General-purpose input stream class and base class 
for other input streams. 


Input file stream class. 
Input stream class for cin. 


Input string stream class. 


General-purpose output stream class and base class 
for other output streams. 


Output file stream class. 
Output stream class for cout, cerr, and clog. 


Output string stream class. 


Input/Output Stream Classes 


iostream 


fstream 
strstream 


stdiostream 


General-purpose input/output stream class and 
base class for other input/output streams. 


Input/output file stream class. 
Input/output string stream class. 


Input/output class for standard I/O files. 


830 lostream Class List 


Stream Buffer Classes 


streambuf Abstract stream buffer base class. 

filebuf Stream buffer class for disk files. 
strstreambuf Stream buffer class for strings. 

stdiobuf Stream buffer class for standard I/O files. 


Predefined Stream Initializer Class 


Iostream_ init Predefined stream initializer class. 


filebuf 831 


Class filebuf : public streambuf 


See Also 


Public Members 


The filebuf class is a derived class of streambuf that is specialized for buffered 
disk file I/O. The buffering is managed entirely within the Microsoft iostream 
Class Library. filebuf member functions call the run-time low-level I/O routines 
(the functions declared in IO.H) such as _sopen, _ read, and _ write. 


The file stream classes, ofstream, ifstream, and fstream, use filebuf member 
functions to fetch and store characters. Some of these member functions are virtual 
functions defined for the streambuf class. 


The reserve area, put area, and get area were introduced in the streambuf class de- 
scription. The put area and the get area are always the same for filebuf objects. 
Also, the get pointer and put pointers are tied; when one moves so does the other. 


#include <fstream.h> 


ifstream, ofstream, streambuf, strstreambuf, stdiobuf 


Construction/Destruction 


filebuf Constructs a filebuf object. 

~filebuf Destroys a filebuf object. 

Operations 

open Opens a file and attaches it to the filebuf object. 

close Flushes any waiting output and closes the attached 
file. 

setmode Sets the file’s mode to binary or text. 

attach Attaches the filebuf object to an open file. 


Status/Information 
fd Returns the stream’s file descriptor. 


is_open Tests whether the file is open. 


832 filebuf::attach 


Member Functions 


Syntax 


Parameters 


Remarks 


Return Value 


Syntax 


Remarks 


See Also 


filebuf::attach 


filebuf* attach( filedesc fd ); 


fd 
A file descriptor as returned by a call to the run-time function _ open or 
_sopen. filedesc is a typedef equivalent to int. 


Attaches this filebuf object to the open file specified by fd. 


NULL when the stream is already attached to a file; otherwise it returns its own 
address. 


filebuf::close 
filebuf* closeQ; 


This function flushes any waiting output, closes the file, and disconnects the file 
from the filebuf object. If an error occurs, the function returns NULL and leaves 
the filebuf object in a closed state. If there is no error, the function returns the 
address of the filebuf object and clears its error state. 


filebuf::open 


syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


filebuf::filebuf 833 


filebut::fd 


filedesc fdQ const; 


Returns the file descriptor associated with the filebuf object; filedesc is a typedef 
equivalent to int. Its value is supplied by the underlying file system. The function 
returns EOF if the object is not attached to a file. 


filebuf::attach 


filebuf::filebuf 


filebufQ); 
filebuf( filedesc fd ); 
filebuf( filedesc fd, char* pr, int nLength ); 


fd 
A file descriptor as returned by a call to the run-time function _ sopen. filedesc 
is a typedef equivalent to int. 


pr 
Pointer to a previously allocated reserve area of length nLength. 


nLength 
The length (in bytes) of the reserve area. 


The three filebuf constructors are described as follows: 


Constructor Description 

filebuf() Constructs a filebuf object without attaching 
it to a file. 

filebuf( filedesc ) Constructs a filebuf object and attaches it to 


an open file. 


filebuf( filedesc, char*, int ) Constructs a filebuf object, attaches it to an 
open file, and initializes it to use a specified 
reserve area. 


834 filebuf::~filebuf 


Syntax 


Remarks 


Syntax 


Remarks 


See Also 


syntax 


Parameters 


filebuf::~filebuf 
~filebufQ); 


Closes the attached file only if that file was opened by the open member function. 


filebuf::is_ open 
int is_open() const; 


Returns a nonzero value if this filebuf object is attached to an open disk file iden- 
tified by a file descriptor; otherwise 0. 


filebuf::open 


filebuf::open 
filebuf* open( const char* szName, int nMode, int nProt = filebuf::openprot ); 


szName 
The name of the file to be opened during construction. 

nMode 
An integer containing mode bits defined as ios enumerators that can be com- 
bined with the OR (| ) operator. See the ofstream constructor for a list of the 
enumerators. 

nProt 
The file protection specification; defaults to the static integer filebuf::openprot 
that is equivalent to filebuf::sh_ compat. The possible nProt values are as 
follows: 


Value Meaning 
filebuf::sh_ compat Compatibility share mode. 


filebuf::sh_none Exclusive mode—no sharing. 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 
Return Value 


See Also 


filebuf::setmode 835 


Value Meaning 
filebuf: :sh_read Read sharing allowed. 
filebuf::sh_ write Write sharing allowed. 


The filebuf::sh_read and filebuf::sh_ write modes can be combined with the 
logical OR (I) operator. 


Opens a disk file and attaches it with this filebuf object. If the file is already open, 
or if there is an error while opening the file, the function returns NULL; otherwise 
it returns the filebuf address. 


filebuf::is_ open, filebuf::close, filebuf: :filebuf 


filebuf::setmode 


int setmode( int nMode = filebuf::text ); 


nMode 
An integer that must be one of the static filebuf constants, as follows: 
Value Meaning 
filebuf: :text Text mode (newline characters translated to and 


from carriage return—linefeed pairs). 


filebuf:: binary Binary mode (no translation). 


This function sets the binary/text mode of the stream’s filebuf object. 
The previous mode if there is no error; otherwise 0. 


ios binary manipulator, ios text manipulator 


836 fstream 


class fstream : public iostream 


Description 


See Also 


Public Members 


The fstream class is an iostream derivative specialized for combined disk file 
input and output. Its constructors automatically create and attach a filebuf buffer 
object. 


The filebuf class documentation describes the get and put areas and their as- 
sociated pointers. Although the filebuf object’s get and put pointers are theoreti- 
cally independent, the get area and the put area cannot both be active at the same 
time. Therefore, when the stream’s mode changes from input to output, the get 
area is emptied and the put area is reinitialized. When the mode changes from out- 
put to input, the put area is flushed and the get area is reinitialized. 


#include <fstream.h> 


ifstream, ofstream, strstream, stdiostream, filebuf 


Construction/Destruction 


fstream Constructs an fstream object. 

~fstream Destroys an fstream object. 

Operations 

open Opens a file and attaches it to the filebuf object 
and thus to the stream. 

close Flushes any waiting output and closes the 
stream’s file. 

setbuf Attaches the specified reserve area to the stream’s 
filebuf object. 

setmode Sets the stream’s mode to binary or text. 

attach | Attaches the stream (through the filebuf object) to 


an open file. 


fstream 837 


Status/Information 
rdbuf Gets the stream’s filebuf object. 
fd Returns the file descriptor associated with the 


stream. 


is_open Tests whether the stream’s file 1s open. 


838 fstream::attach 


Member Functions 


syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


fstream::attach 


void attach( filedesc fd ); 


fd 
A file descriptor as returned by a call to the run-time function _open or 
_sopen; filedesc is a typedef equivalent to int. 
Attaches this stream to the open file specified by fd. The function fails when the 
stream is already attached to a file. In that case, the function sets ios::failbit in the 
stream’s error state. 


filebuf::attach, fstream::fd 


fstream::close 


void close(); 


Calls the close member function for the associated filebuf object. This function, in 
turn, flushes any waiting output, closes the file, and disconnects the file from the 
filebuf object. The filebuf object is not destroyed. 


The stream’s error state is cleared unless the call to filebuf::close fails. 


filebuf::close, fstream::open, fstream::is_open 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


fstream::fstream 839 


fstream::fd 
filedesc fd() const; 


Returns the file descriptor associated with the stream. filedesc is a typedef equiv- 
alent to int. Its value is supplied by the underlying file system. 


filebuf::fd, fstream::attach 


fstream::fstream 


fstream(); 
fstream( const char* szName, int nMode, int nProt = filebuf::openprot ); 
fstream( filedesc fd ); 


fstream( filedesc fd, char* pch, int nLength ); 


szName 
The name of the file to be opened during construction. 


nMode 
An integer that contains mode bits defined as ios enumerators that can be com- 
bined with the bitwise-OR (|) operator: 


Value Meaning 


ios::app The function performs a seek to the end of file. When 
new bytes are written to the file, they are always 
appended to the end, even if the position is moved with 
the ostream::seekp function. 


ios::ate The function performs a seek to the end of file. When 
the first new byte is written to the file, it is appended to 
the end, but when subsequent bytes are written, they are 
written to the current position. 
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fstream::fstream 


Value 


ios::in 


ios::out 


ios::trunc 


ios::nocreate 
ios::noreplace 


ios:: binary 


Meaning 


The file is opened for input. The original file (if it 
exists), will not be truncated. 


The file 1s opened for output. 


If the file already exists, its contents are discarded. This 
mode is implied if ios::out is specified and ios::ate, 
ios::app, and ios:in are not specified. 


If the file does not already exist, the function fails. 
If the file already exists, the function fails. 


Opens the file in binary mode (the default is text mode). 


Note that there is no ios::in or ios::out default mode for fstream objects. You 
must specify both modes if your fstream object must both read and write files. 


nProt 


The file protection specification; defaults to the static integer filebuf::openprot 
that is equivalent to filebuf::sh_ compat. The possible nProt values are as 


follows: 
Value Meaning 
filebuf::sh_ compat Compatibility share mode. 


filebuf::sh_none 
filebuf::sh_read 


filebuf::sh_ write 


Exclusive mode—no sharing. 
Read sharing allowed. 


Write sharing allowed. 


The filebuf::sh_ read and filebuf::sh_ write modes can be combined with the 
logical OR (I) operator. 


fd 


A file descriptor as returned by a call to the run-time function _ open or 
_sopen. filedesc is a typedef equivalent to int. 


pch 


Pointer to a previously allocated reserve area of length nLength. A NULL value 
(or nLength = 0) indicates that the stream will be unbuffered. 


nLength 


The length (in bytes) of the reserve area (O = unbuffered). 


Remarks 


Syntax 


Remarks 


fstream::~fstream 841 


The four fstream constructors are described as follows: 


Constructor Description 

fstream() Constructs an fstream object without 
opening a file. 

f{stream( const char%, int, int ) Contructs an fstream object, opening the 
specified file. 

fstream( filedesc ) Constructs an fstream object that is 


attached to an open file. 


fstream( filedesc, char*, int ) Constructs an fstream object that is 
associated with a filebuf object. The 
filebuf object is attached to an open file 
and to a specified reserve area. 


All fstream constructors construct a filebuf object. The first three use an inter- 
nally allocated reserve area, but the fourth uses a user-allocated area. The user- 
allocated area is not automatically released during destruction. 


fstream::~fstream 


~fstream(); 


Flushes the buffer, then destroys an fstream object, along with its associated 
filebuf object. The file is closed only if it was opened by the constructor or by the 
open member function. 


The filebuf destructor releases the reserve buffer only if it was internally allocated. 


842 fstream::is_ open 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


fstream::is_ open 


int is_open() const; 


Returns a nonzero value if this stream is attached to an open disk file identified by 
a file descriptor; otherwise 0. 


filebuf::is_ open, fstream: open, fstream::close 


fstream::open 


void open( const char* szName, int nMode, int nProt = filebuf::openprot ); 


szName 
The name of the file to be opened during construction. 


nMode 
An integer containing mode bits defined as ios enumerators that can be com- 
bined with the OR (|) operator. See the fstream constructor for a list of the 
enumerators. The ios::out mode 1s implied. 


nProt 
The file protection specification; defaults to the static integer 
filebuf::openprot. See the fstream constructor for a list of the other allowed 
values. 


Opens a disk file and attaches it to the stream’s filebuf object. If the filebuf object 
is already attached to an open file, or if a filebuf call fails, the ios::failbit is set. If 
the file is not found, then the ios::failbit is set only if the ios::nocreate mode 

was used. 


filebuf::open, fstream::fstream, fstream::close, fstream::is_ open 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 


fstream::setbuf 843 


fstream::rdbuf 
filebuf* rdbuf() const; 


Returns a pointer to the filebuf buffer object that is associated with this stream. 
(Note that this is not the character buffer; the filebuf object contains a pointer to 
the character area.) 


fstream::setbuf 


streambuf* setbuf( char* pch, int nLength ); 


pch 
A pointer to a previously allocated reserve area of length nLength. A NULL 
value indicates an unbuffered stream. 


nLength 
The length (in bytes) of the reserve area. A length of 0 indicates an unbuffered 
stream. 


Attaches the specified reserve area to the stream’s filebuf object. If the file is open 
and a buffer has already been allocated, the function returns NULL; otherwise it 
returns a pointer to the filebuf cast as a streambuf. The reserve area will not be re- 
leased by the destructor. 


44 _ fstream::setmode 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


fstream::setmode 


int setmode( int nMode = filebuf::text ); 


nMode 
An integer that must be one of the static filebuf constants, as follows: 
Value | Meaning 
filebuf::text Text mode (newline characters translated to and from 


carriage return—linefeed pairs). 


filebuf::binary | Binary mode (no translation). 


This function sets the binary/text mode of the stream’s filebuf object. It may be 
called only after the file is opened. 


The previous mode; —1 if the parameter is invalid, the file is not open, or the mode 
cannnot be changed. 


ios binary manipulator, ios text manipulator 


ifstream 845 


Class ifstream : public istream 


Description The ifstream class is an istream derivative specialized for disk file input. Its con- 


structors automatically create and attach a filebuf buffer object. 


The filebuf class documentation describes the get and put areas and their as- 
sociated pointers. Only the get area and the get pointer are active for the ifstream 
class. 


#include <fstream.h> 


See Also filebuf, streambuf, ofstream, fstream 


Public Members 


Construction/Destruction 


ifstream Constructs an ifstream object. 

~ifstream Destroys an ifstream object. 

Operations 

open Opens a file and attaches it to the filebuf object 
and thus to the stream. 

close Closes the stream’s file. 

setbuf Associates the specified reserve area to the 
stream’s filebuf object. 

setmode Sets the stream’s mode to binary or text. 

attach Attaches the stream (through the filebuf object) to 
an open file. 

Status/Information 

rdbuf Gets the stream’s filebuf object. 

fd Returns the file descriptor associated with the 


is_open 


stream. 


Tests whether the stream’s file 1s open. 
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Member Functions 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


lfstream::attach 


void attach( filedesc fd ); 


fd 
A file descriptor as returned by a call to the run-time function _ open or 
_sopen; filedesc is a typedef equivalent to int. 


Attaches this stream to the open file specified by fd. The function fails when the 
stream is already attached to a file. In that case, the function sets ios::failbit in the 


stream’s error state. 


filebuf::attach, ifstream::fd 


ifstream::close 


void close(); 


Calls the close member function for the associated filebuf object. This function, in 
turn, closes the file and disconnects the file from the filebuf object. The filebuf ob- 
ject is not destroyed. 


The stream’s error state is cleared unless the call to filebuf::close fails. 


filebuf::close, ifstream::open, ifstream::is_ open 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


ifstream::ifstream 847 


ifstream::fd 
filedesc fd() const; 


Returns the file descriptor associated with the stream; filedesc is a typedef equiv- 
alent to int. Its value is supplied by the underlying file system. 


filebuf::fd, ifstream::attach 


lfstream::ifstream 


ifstream(); 


ifstream( const char* szName, int nMode = ios::in, 
int nProt = filebuf::openprot ); 


ifstream( filedesc fd ); 


ifstream( filedesc fd, char* pch, int nLength ); 


szName 
The name of the file to be opened during construction. 


nMode 
An integer that contains mode bits defined as ios enumerators that can be com- 
bined with the bitwise-OR (I) operator: 


Value Meaning 
ios::in The file is opened for input (default). 


ios::nocreate If the file does not already exist, the function fails. 


ios: :binary Opens the file in binary mode (the default is text mode). 


Note that the ios::nocreate flag is necessary if you intend to test for the file’s 
existence (the usual case). 


nProt 
The file protection specification; defaults to the static integer filebuf::openprot 
that is equivalent to filebuf::sh_ compat. The possible nProt values are as 
follows: 
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Remarks 


ifstream::ifstream 


Value Meaning 

filebuf::sh_ compat Compatibility share mode. 
filebuf::sh_none Exclusive mode—no sharing. 
filebuf::sh_ read Read sharing allowed. 
filebuf::sh_ write Write sharing allowed. 


The filebuf::sh_read and filebuf::sh_ write modes can be combined with the 


logical OR (I ) operator. 
fd 


A file descriptor as returned by a call to the run-time function _ open or 
_sopen; filedesc is a typedef equivalent to int. 


pch 


Pointer to a previously allocated reserve area of length nLength. A NULL value 


(or nLength = 0) indicates that the stream will be unbuffered. 


nLength 


The length (in bytes) of the reserve area (0 = unbuffered). 


The four ifstream constructors are described as follows: 


Constructor 


ifstream() 
ifstream( const char’, int, int ) 
ifstream( filedesc ) 


ifstream( filedesc, char*, int ) 


All ifstream constructors construct a filebuf object. The first three use an inter- 


Description 


Constructs an ifstream object 
without opening a file. 


Contructs an ifstream object, 
opening the specified file. 


Constructs an ifstream object that is 
attached to an open file. 


Constructs an ifstream object that is 
associated with a filebuf object. The 
filebuf object is attached to an open 
file and to a specified reserve area. 


nally allocated reserve area, but the fourth uses a user-allocated area. 


Syntax 


Remarks 


Syntax 


- Remarks 


See Also 


Syntax 


Parameters 


ifstream::open 849 


ifstream::~ifstream 


~ifstream(); 


Destroys an ifstream object along with its associated filebuf object. The file is 
closed only if was opened by the constructor or by the open member function. 


The filebuf destructor releases the reserve buffer only if it was internally allocated. 


ifstream::is_ open 
int is_open() const; 


Returns a nonzero value if this stream is attached to an open disk file identified by 
a file descriptor; otherwise 0. 


filebuf::is_ open, ifstream::open, ifstream::close 


ifstream::open 


void open( const char* szName, int nMode = ios::in, 
int nProt = filebuf::openprot ); 


szName 
The name of the file to be opened during construction. 


nMode 
An integer containing bits defined as ios enumerators that can be combined 
with the OR (|) operator. See the ifstream constructor for a list of the enumera- 
tors. The ios::in mode is implied. 


nProt 
The file protection specification; defaults to the static integer 
filebuf::openprot. See the ifstream constructor for a list of the other 
allowed values. 


850 ifstream::rdbuf 


Remarks 


See Also 


syntax 


Remarks 


Syntax 


Parameters 


Remarks 


Opens a disk file and attaches it to the stream’s filebuf object. If the filebuf object 
is already attached to an open file, or if a filebuf call fails, the ios::failbit is set. If 
the file is not found, then the ios::failbit is set only if the ios::nocreate mode 

was used. 


filebuf::open, ifstream::ifstream, ifstream::close, ifstream::is_open 


ifstream::rdbuf 
filebuf* rdbuf() const; 


Returns a pointer to the filebuf buffer object that is associated with this stream. 
(Note that this is not the character buffer; the filebuf object contains a pointer to 
the character area.) 


lfstream::setbuf 


streambuf* setbuf( char* pch, int nLength ); 


pch 
A pointer to a previously allocated reserve area of length nLength. A NULL 
value indicates an unbuffered stream. 


nLength 
The length (in bytes) of the reserve area. A length of 0 indicates an unbuffered 
stream. 


Attaches the specified reserve area to the stream’s filebuf object. If the file is open 
and a buffer has already been allocated, the function returns NULL; otherwise it 
returns a pointer to the filebuf, which is cast as a streambuf. The reserve area will 
not be released by the destructor. 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


ifstream::setmode 851 


ifstream::setmode 


int setmode( int nMode = filebuf::text ); 


nMode 
An integer that must be one of the static filebuf constants, as follows: 
Value Meaning 
filebuf: :text Text mode (newline characters translated to and from 


carriage return—linefeed pairs). 


filebuf: :binary Binary mode (no translation). 


This function sets the binary/text mode of the stream’s filebuf object. It may be 
called only after the file is opened. 


The previous mode; —1 if the parameter is invalid, the file is not open, or the mode 
cannnot be changed. 


ios binary manipulator, ios text manipulator 


852 ios 


class ios 


See Also 


Public Members 


As the 1ostream class hierarchy diagram shows, the ios class is the base class for 
all the input/output stream classes. While ios is not technically an abstract base 
class, you will not usually construct ios objects, nor will you derive classes 
directly from ios. Instead, you will use the derived classes istream and ostream 
or other derived classes. 


Even though you will not use ios directly, you will be using many of the inherited 
member functions and data members described here. Remember that these in- 
herited member function descriptions are not duplicated for derived classes. 


#include <iostream.h> 


istream, ostream 


Data Members (static) 


basefield Mask for obtaining the conversion base flags (dec, 
oct, or hex). 

adjustfield Mask for obtaining the field padding flags (left, 
right, or internal). 

floatfield Mask for obtaining the numeric format (scientific 
or fixed). 


Construction/Destruction 
10S Constructor for use in derived classes. 


~i0s Virtual destructor. 


Flag and Format Access Functions 


flags Sets or reads the stream’s format flags. 

setf Manipulates the stream’s format flags. 

unsetf Clears the stream’s format flags. 

fill Sets or reads the stream’s fill character. 

precision Sets or reads the stream’s floating-point format dis- 
play precision. 


width Sets or reads the stream’s output field width. 


Status-Testing Functions 
good 

bad 

eof 

fail 


rdstate 


clear 


los 853 


Indicates good stream status. 
Indicates a serious I/O error. 
Indicates end of file. 


Indicates a serious I/O error or a possibly recover- 
able I/O formatting error. 


Returns the stream’s error flags. 


Sets or clears the stream’s error flags. 


User-Defined Format Flags 


bitalloc 


xalloc 


iword 


pword 


Other Functions 
delbuf 


rdbuf 


sync_with_stdio 
tie 


Operators 
operator void*() 


operator !() 


Protected Members 


init 


Provides a mask for an unused format bit in the 
stream’s private flags variable (static function). 


Provides an index to an unused word in an array re- 
served for special-purpose stream state variables 
(static function). 


Converts the index provided by xalloc to a refer- 
ence (valid only until the next xalloc). 


Converts the index provided by xalloc to a pointer 
(valid only until the next xalloc). 


Controls the connection of streambuf deletion 
with ios destruction. 


Gets the stream’s streambuf object. 


Synchronizes the predefined objects cin, cout, 
cerr, and clog with the standard I/O system. 


Ties a specified ostream to this stream. 


Converts a stream to a pointer that can be used 
only for error checking. 


Returns a nonzero value if a stream I/O error has 
occurred. 


Associates a Streambuf object with this stream. 


854 los 


Manipulators 


los Manipulators 
dec 


hex 
oct 
binary 


text 


Causes the interpretation of subsequent fields in 
decimal format (the default mode). 


Causes the interpretation of subsequent fields in 
hexadecimal format. 


Causes the interpretation of subsequent fields in 
octal format. 


Sets the stream’s mode to binary (stream must 
have an associated filebuf buffer). 


Sets the stream’s mode to text—the default mode 
(stream must have an associated filebuf buffer). 


Parameterized Manipulators 


(#include <iomanip.h> required) 


setiosflags 
resetiosflags 
setfill 
setprecision 


setw 


Sets the stream’s format flags. 

Resets the stream’s format flags. 

Sets the stream’s fill character. 

Sets the stream’s floating-point display precision. 


Sets the stream’s field width (for the next field 
only). 


1os::bitalloc 855 


Member Functions 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


los::bad 
int bad() const; 


Returns a nonzero value to indicate a serious I/O error. This condition corresponds 
to the badbit error state being set. Do not continue I/O operations on the stream in 
this situation. 


10s::good, ios::fail, ios::rdstate 


los::bitalloc 


static long bitallocQ; 


The ios class currently defines 15 format flag bits accessible through flags and 
other member functions. These bits reside in a 32-bit private ios data member and 
are accessed through enumerators such as ios::left and ios::hex. 


The bitalloc member function provides a mask for a previously unused bit in the 
data member. Once you obtain the mask, you can use it to set or test the corre- 
sponding custom flag bit in conjunction with the ios member functions and 
manipulators listed below under “See Also.” 


ios::flags, ios::setf, ios::unsetf, ios setiosflags manipulator, ios resetiosflags 
manipulator 


856 ios::clear 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


los::clear 
void clear( int nState = 0 )s; 


nState 
If 0, all error bits are cleared; otherwise bits are set according to the following 
masks (ios enumerators) that can be combined using the bitwise-OR (| ) 
operator: 


Value Meaning 

ios::goodbit No error condition (no bits set) 

ios: :eofbit End of file reached 

ios: :failbit A possibly recoverable formatting or conversion error 
ios::badbit A severe I/O error 


Sets or clears the error-state flags. The rdstate function can be used to read the 
current error state. 


ios: :rdstate, ios::good, ios::bad, ios::eof 


ios::delbuf 


void delbuf( int nDelFlag ); 


int delbuf() const; 


nDelFlag 
A nonzero value indicates that ~ios should delete the stream’s attached 
streambuf object. A 0 value prevents deletion. 


The first overloaded delbuf function assigns a value to the stream’s buffer- 
deletion flag. 


The second function returns the current value of the flag. 


los::fill = 857 
This function is public only because it is accessed by the Iostream_ init class. 


Treat it as protected. 


See Also ios::rdbuf, ios::~ios 


los::eof 
Syntax int eof() const; 


Remarks Returns a nonzero value if end of file has been reached. This condition corre- 
sponds to the eofbit error flag being set. 


ios::fail 
Syntax int failQ const; 


Remarks Returns a nonzero value if any I/O error (not end of file) has occurred. This condi- 
tion corresponds to either the badbit or failbit error flag being set. If a call to bad 
returns 0, you can assume that the error condition is nonfatal and that you can 
probably continue processing after you clear the flags. 


See Also ios::bad, ios::clear 


los::fill 


Syntax char fill( char cFill ); 
char fillQ const; 
Parameters cFill 


The new fill character to be used as padding between fields. 


858 los::flags 


Remarks The first overloaded function sets the stream’s internal fill character variable to 
cFill and returns the previous value. The default fill character is a space. 


The second fill function returns the stream’s fill character. 


See Also ios setfill manipulator 


los::flags 


Syntax long flags( long /Flags ); 
long flags() const; 
Parameters lFlags 


The new format flag values for the stream. The values are specified by the fol- 
lowing bit masks (ios enumerators) that can be combined using the bitwise-OR 
(|) operator: 


Value Meaning 

ios::skipws Skip white space on input. 

ios: :left Left-align values; pad on the right with the fill character. 

ios::right Right-align values; pad on the left with the fill character 
(default alignment). 

ios::internal Add fill characters after any leading sign or base 
indication, but before the value. 

ios::dec Format numeric values as base 10 (decimal) (default 
radix). 

ios::oct Format numeric values as base 8 (octal). 

ios::hex Format numeric values as base 16 (hexadecimal). 

ios::showbase Display numeric constants in a format that can be read 


by the C++ compiler. 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


Value 


10S: 


ios: 


i0S: 
10S: 
10S: 


10S: 


10S: 


:sshowpoint 
:uppercase 


:showpos 
scientific 
fixed 


sunitbuf 


:Stdio 


los::good 859 


Meaning 


Show decimal point and trailing zeros for floating-point 
values. 


Display uppercase A through F for hexadecimal values 
and E for scientific values. 


Show plus signs (+) for positive values. 
Display floating-point numbers in scientific format. 
Display floating-point numbers in fixed format. 


Cause ostream::osfx to flush the stream after each 
insertion. By default, cerr is unit buffered. 


Cause ostream::osfx to flush stdout and stderr after 
each insertion. 


The first overloaded flags function sets the stream’s internal flags variable to 
[Flags and returns the previous value. 


The second function returns the stream’s current flags. 


ios::setf, ios::unsetf, ios setiosflags manipulator, ios resetiosflags manipulator, 
ios::adjustfield, ios::basefield, ios: :floatfield 


los::good 


int good() const; 


Returns a nonzero value if all error bits are clear. Note that the good member func- 
tion is not simply the inverse of the bad function. 


ios::bad, ios::fail, ios::rdstate 
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syntax 


Parameters 


Remarks 


Syntax 


Remarks 


Syntax 


Parameters 
Remarks 


See Also 


l0S::10S 
ios( streambuf* psb ); 


psb 
A pointer to an existing streambuf object. 


Constructor for ios. You will seldom need to invoke this constructor except in 
derived classes. Generally, you will be deriving classes not from ios but from 
istream, ostream, and iostream. 


l0S::~10S 
virtual ~ios(); 


Virtual destructor for ios. 


ios::iword 
long& iword( int n/ndex ) const; 


nIndex 
An index into a table of words that are associated with the tos object. 


The xalloc member function provides the index into the table of special-purpose 
words. The iword function converts that index to a reference to a 32-bit word. 


ios::xalloc, ios::pword 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


los::pword 861 


los::precision 
int precision( int np ); 


int precision() const; 


np 
An integer that indicates the number of significant digits or significant decimal 
digits to be used for floating-point display. 


The first overloaded precision function sets the stream’s internal floating-point 
precision variable to np and returns the previous value. The default precision is six 
digits. If the display format is scientific or fixed, then the precision indicates the 
number of digits after the decimal point. If the format is automatic (neither float- 
ing point nor fixed), then the precision indicates the total number of significant 
digits. 


The second function returns the stream’s current precision value. 


ios setprecision manipulator 


los::pword 


void* & pword( int n/ndex ) const; 


nindex 
An index into a table of words that are associated with the ios object. 


The xalloc member function provides the index into the table of special-purpose 
words. The pword function converts that index to a reference to a pointer to a 32- 
bit word. 


ios::xalloc, ios::iword 


862 los::rdbuf 


Syntax 


Remarks 


Syntax 


Remarks 


See Also 


ios::rdbuf 
streambuf* rdbuf() const; 


Returns a pointer to the streambuf object that is associated with this stream. The 
rdbuf function is useful when you need to call streambuf member functions. 


los::rdstate 


int rdstate() const; 


Returns the current error state as specified by the following masks (ios 
enumerators): 


Value Meaning 

ios::goodbit No error condition 

ios::eofbit End of file reached 

ios: :failbit A possibly recoverable formatting or conversion error 
ios::badbit A severe I/O error or unknown state 


The returned value can be tested against a mask with the AND (&) operator. 


ios::clear 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


los::sync_with_stdio 863 


los::setf 


long setf( long /Flags ); 


long setf( long /Flags, long /Mask ); 


[Flags 
Format flag bit values. See the flags member function for a list of format flags. 
These flags can be combined by using the bitwise-OR (| ) operator. 


[Mask 
Format flag bit mask. 


The first overloaded setf function turns on only those format bits that are specified 
by 1s in /Flags. It returns a long that contains the previous value of all the flags. 


The second function alters those format bits specified by 1s in /Mask. The new 
values of those format bits are determined by the corresponding bits in /Flags. It 
returns a long that contains the previous value of all the flags. 


ios::flags, ios::unsetf, ios setiosflags manipulator 


los::sync_with_stdio 
static void sync_ with_ stdioQ); 


Synchronizes the C++ streams with the standard I/O system. The first time this 
function is called, it resets the predefined streams (cin, cout, cerr, clog) to use a 
stdiobuf object rather than a filebuf object. After that, I/O using these streams can 
be freely mixed with I/O using stdin, stdout, and stderr. Some performance 
decrease will result because there is buffering both in the stream class and in the 
standard I/O file system. 


After the call to syne_ with_stdio, the ios::stdio bit is set for all affected prede- 
fined stream objects, and cout is set to unit buffered mode. 
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Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Remarks 


See Also 


los::tle 
ostream* tie( ostream* pos ); 


ostream* tie() const; 


pos 
A pointer to an ostream object. 


The first overloaded tie function ties this stream to the specified ostream and re- 
turns the value of the previous tie pointer (NULL if this stream was not previously 
tied). A stream tie enables automatic flushing of the ostream in response to (1) a 
need for more characters or (2) the presence of characters to be consumed. 


By default, cin is initially tied to cout so that attempts to get more characters from 
standard input may result in flushing standard output. In addition, cerr and clog 
are tied to cout by default. 


The second function returns the value of the previous tie pointer (NULL if this 
stream was not previously tied). 


ios::unsetf 


long unsetf( long /Flags ); 


lFlags | 
Format flag bit values. See the flags member function for a list of format flags. 


Clears the format flags specified by 1s in /Flags. It returns a long that contains the 
previous value of all the flags. 


ios: :flags, ios::setf, ios resetiosflags manipulator 


ios::xalloc 865 


los::width 
Syntax int width( int nw ); 


int width() const; 


Parameters nw 
The minimum field width in characters. 


Remarks The first overloaded width function sets the stream’s internal field width variable 
to nw. When the width is O (the default), inserters insert only as many characters 
as necessary to represent the inserted value. When the width is not 0, the inserters 
pad the field with the stream’s fill character, up to nw. If the unpadded repre- 
sentation of the field is larger than nw, the field is not truncated. Thus nw is a min- 
imum field width. 


The internal width value is reset to 0 after each insertion or extraction. 


The second overloaded width function returns the current value of the stream’s 
width variable. 


See Also ios setw manipulator 


los::xalloc 
Syntax static int xalloc(); 


Remarks Provides extra ios object state variables without the need for class derivation. It 
does so by returning an index to an unused 32-bit word in an internal array. This 
index can be subsequently converted into a reference or pointer by using the 
iword or pword member functions. 


Any call to xalloc invalidates values returned by previous calls to iword and 
pword. 


See Also ios::iword, ios::pword 
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Operators 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


ios::operator void* () 
operator void* () const; 


An operator that converts a stream to a pointer that can be compared to 0. The con- 
version returns 0 if either failbit or badbit is set in the stream’s error state. See 
rdstate for a description of the error state masks. A nonzero pointer is not meant 
to be dereferenced. 


i0S::g00d, ios::fail 


ios::operator !() 


int operator !() const; 


Returns a nonzero value if either failbit or badbit are set in the stream’s error 
state. See rdstate for a description of the error state masks. 


i0s::good, ios: :fail 


ios::floatfield 


Data Members 


Syntax 
Remarks 


Example 


See Also 


syntax 
Remarks 


Example 


See Also 


Syntax 


Remarks 


Example 


See Also 


ios::adjustfield 
static const long adjustfield; 
A mask that can be used to obtain the padding flag bits (left, right, or internal). 


extern ostream os; 
if€ C-os.tlagst).& Tos eradjustfield..) =] Tosesle6rt.). cca 


ios: :flags 


los::basefield 


static const long basefield; 
A mask that can be used to obtain the current radix flag bits (dec, oct, or hex). 


extern ostream OS; 
if( ( os.flags() & ios::basefield ) == ios::hex ) ..... 


ios: :flags 


ios::floatfield 


static const long floatfield; 


A mask that can be used to obtain floating-point format flag bits (scientific or 
fixed). 


extern ostream os; 
if( ( os.flags() & ios::floatfield ) == ios::scientific ) ..... 


ios: :flags 
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Manipulators 


Syntax 


Remarks 


See Also 


Syntax 
Remarks 


See Also 


Syntax 
Remarks 


See Also 


ios& binary 


binary 


#include <fstream.h> 


Sets the stream’s mode to binary. The default mode is text. 


The stream must have an associated filebuf buffer. 


ios text manipulator, ofstream::setmode, ifstream::setmode, filebuf::setmode 


ios& dec 


dec 
Sets the format conversion base to 10 (decimal). 


ios hex manipulator, 1os oct manipulator 


los& hex 


hex 
Sets the format conversion base to 16 (hexadecimal). 


ios dec manipulator, ios oct manipulator 


Syntax 
Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Remarks 


setfill 869 


ios& oct 


oct 
Sets the format conversion base to 8 (octal). 


ios dec manipulator, ios hex manipulator 


resetiosflags 


SMANIP( long ) resetiosflags( long /Flags ); 


#include <iomanip.h> 


lFlags 
Format flag bit values. See the flags member function for a list of format flags. 
These flags can be combined by using the OR (| ) operator. 


This parameterized manipulator clears only the specified format flags. This setting 
remains in effect until the next change. 


setfili 


SMANIP( int ) setfill( int nFill ); 


#include <iomanip.h> 


nFill 
The new fill character to be used as padding between fields. 


This parameterized manipulator sets the stream’s fill character. The default is a 
space. This setting remains in effect until the next change. 


870 setiosflags 


Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Remarks 


setiosflags 


SMANIP( long ) setiosflags( long /Flags ); 


#include <iomanip.h> 


lFlags 
Format flag bit values. See the flags member function for a list of format flags. 
These flags can be combined by using the OR (| ) operator. 


This parameterized manipulator sets only the specified format flags. This setting 
remains 1n effect until the next change. 


setprecision 


SMANIP( int ) setprecision( int np ); 


#include <iomanip.h> 


np 7 
An integer that indicates the number of significant digits or significant decimal 
digits to be used for floating-point display. 


This parameterized manipulator sets the stream’s internal floating-point precision 
variable to np. The default precision is six digits. If the display format is scientific 
or fixed, then the precision indicates the number of digits after the decimal point. 
If the format is automatic (neither floating point nor fixed), then the precision indi- 
cates the total number of significant digits. 


This setting remains in effect until the next change. | 


Syntax 


Parameters 


Remarks 


Syntax 


Remarks 


See Also 


ios& text 871 


setw 
SMANIP( int ) setw( int nw ); 
#include <iomanip.h> 


nw 
The field width in characters. 


This parameterized manipulator sets the stream’s internal field width parameter. 
See the width member function for more information. This setting remains in ef- 
fect only for the next insertion. 


ios& text 


text 


#include <fstream.h> 


Sets the stream’s mode to text (the default mode). 


The stream must have an associated filebuf buffer. 


ios binary manipulator, ofstream::setmode, ifstream::setmode, 
filebuf::setmode 


872 lostream 


class iostream : public istream, public ostream 


Derivation 


See Also 


Public Members 


The iostream class provides the basic capability for sequential and random-access 
I/O. It inherits functionality from both the istream and ostream classes. 


The iostream class works in conjunction with classes derived from streambuf 
(for example, filebuf). In fact, most of the iostream “personality” comes from its 
attached streambuf class. You can use iostream objects for sequential disk I/O if 
you first construct an appropriate filebuf object. More often, you will use objects 
of classes fstream and strstream. 


For derivation suggestions, see the istream and ostream classes. 
#include <iostream.h> : 
istream, ostream, fstream, strstream, stdiostream 


iostream Constructs an iostream object that is attached to 
an existing streambuf object. 


~iostream Destroys an iostream object. 


Protected Members 


iostream Constructs an iostream object. 


iostream::~iostream 873 


Member Functions 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


lostream::iostream 


Public: 
iostream( streambuf* psb ); 


Protected: 
iostream( ); 


psb 
A pointer to an existing streambuf object (or an object of a derived class). 


Constructs an object of type lostream. 


10S::init 


lostream::~iostream 


virtual ~iostream(); 


Virtual destructor for the iostream class. 


874 lostream_ init 


class lostream_ init 


The Iostream_ init class is a static class that initializes the predefined stream ob- 
jects cin, cout, cerr, and clog. A single object of this class is constructed “invis- 
ibly” in response to the reference of any of the predefined objects. The class is 
documented for completeness only. You will not normally construct objects of this 


class. 
#include <iostream.h> 
Public Members 
Iostream_ init A constructor that initializes cin, cout, cerr, 
and clog. 
~lostream_ init The destructor for the Iostream_ init class. 


Member Functions 


lostream_ init::lostream_ init 


Syntax Iostream_init(); 
Remarks Iostream_ init constructor that initializes cin, cout, cerr, and clog. For internal 
use only. 


lostream_ init::~lostream_ init 


syntax ~lostream_init(); 


Remarks Iostream_ init destructor. For internal use only. 


istream 875 


class istream : virtual public ios 


The istream class provides the basic capability for sequential and random-access 
input. An istream object has a streambuf-derived object attached, and the two 
classes work together; the istream class does the formatting, and the streambuf 
class does the low-level buffered input. 


You can use istream objects for sequential disk input if you first construct an ap- 

propriate filebuf object. More often, you will use the predefined stream object cin 
(which is actually an object of class istream_ withassign), or you will use objects 
of classes ifstream (disk file streams) and istrstream (string streams). 


Derivation It is not always necessary to derive from istream in order to add functionality to a 
stream; consider deriving from streambuf instead, as illustrated in Chapter 19 of 
the Class Libraries User’s Guide. The ifstream and istrstream classes are ex- 
amples of istream-derived classes that construct member objects of predetermined 
derived streambuf classes. 


You can add manipulators without deriving a new class. 


If you add new extraction operators for a derived istream class, then the rules of 
C++ dictate that you must reimplement all the base class extraction operators. See 
the “Derivation” section of class ostream for an efficient reimplementation tech- 
nique. 


#include <iostream.h> 


See Also streambuf, ifstream, istrstream, istream_ withassign 


Public Members 


Construction/Destruction 


istream Constructs an istream object attached to an 
existing object of a streambuf-derived class. 


~istream Destroys an istream object. 


Prefix/Suffix Functions 


ipfx Check for error conditions prior to extraction 
operations (input prefix function). 


isfx Called after extraction operations (input suffix 
function). 


876 


Input Functions 
get 


getline 


read 
ignore 


peek 
gcount 


eatwhite 


Other Functions 
putback 


sync 


seekg 
tellg 


Operators 
operator >> 


Protected Members 


Manipulators 


istream 


ws 


Extracts characters from the stream up to, but not 
including, delimiters. 


Extracts characters from the stream (extracts and 
discards delimiters). 


Extracts data from the stream. 
Extracts and discards characters. 


Returns a character without extracting it from the 
stream. 


Counts the characters extracted in the last unfor- 
matted operation. 


Extracts leading white space. 


Puts characters back to the stream. 


Synchronizes the stream buffer with the external 
source of characters. 


Changes the stream’s get pointer. 


Gets the value of the stream’s get pointer. 


Extraction operator for various types. 


Constructs an istream object. 


Extracts leading white space. 


istream::gcount 877 


Member Functions 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


istream::eatwhite 


void eatwhiteQ); 


Extracts white space from the stream by advancing the get pointer past spaces 
and tabs. 


istream ws manipulator 


istream::gcount 


int gcount() const; 
Returns the number of characters extracted by the last unformatted input function. 
Formatted extraction operators may call unformatted input functions and thus reset 


this number. 


istream::get, istream::getline, istream::ignore, istream::read 


878 istream::get 


Syntax 


Parameters 


Remarks 


istream::get 


int get(); 


istream& get( char* pch, int nCount, char delim = '\n' ); 
istream& get( unsigned char* puch, int nCount, char delim = '\n" ); 


istream& get( signed char* psch, int nCount, char delim = '\n' ); 


istream& get( char& rch ); 
istream& get( unsigned char& ruch ); 


istream& get( signed char& rsch ); 


istream& get( streambuf& rsb, char delim = '\n' ); 


pch, puch, psch 
A pointer to a character array. 


nCount 
The maximum number of characters to store, including the terminating NULL. 


delim 
The delimiter character (defaults to newline). 


rch, ruch, rsch 
A reference to a character. 


rsb 
A reference to an object of a streambuf-derived class. 


These functions extract data from an input stream as follows: 


Variation Description 

get(); Extracts a single character from the stream and 
returns it. 

get( char*, int, char ); Extracts characters from the stream until either 


delim is found, the limit nCount is reached, or 
the end of file is reached. The characters are 
stored in the array followed by a null terminator. 


See Also 


Syntax 


Parameters 


istream::getline 879 


Variation Description 


get( char& ); Extracts a single character from the stream and 
stores it as specified by the reference argument. 


get( streambuf&, char ); Gets characters from the stream and stores them 
in a Streambuf object until the delimiter is 
found or the end of the file is reached. The 
ios: :failbit flag is set if the streambuf output 
operation fails. 


In all cases, the delimiter is neither extracted from the stream nor returned by the 
function. The getline function, in contrast, extracts the delimiter but does not 
Store it. 


istream:: getline, istream::read, istream::ignore, istream::gcount 


istream::getline 


istream& getline( char* pch, int nCount, char delim = '\n" ); 
istream& getline( unsigned char* puch, int nCount, char delim = '\n' ); 


istream& getline( signed char* psch, int nCount, char delim = '\n' ); 


pch, puch, psch 
A pointer to a character array. 


nCount 
The maximum number of characters to store, including the terminating NULL. 


delim 
The delimiter character (defaults to newline). 


880 istream::ignore 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Remarks 


Extracts characters from the stream until either the delimiter delim is found, the 
limit nCount—1 is reached, or end of file is reached. The characters are stored in 
the specified array followed by a null terminator. If the delimiter is found, it is ex- 
tracted but not stored. 


The get function, in contrast, neither extracts nor stores the delimiter. 


istream::get, istream::read 


istream::ignore 


istream& ignore( int nCount = 1, int delim = EOF ); 


nCount 
The maximum number of characters to extract. 


delim 
The delimiter character (defaults to EOF). 


Extracts and discards up to nCount characters. Extraction stops if the delimiter 
delim is extracted or the end of file is reached. If delim = EOF (the default), then 
only the end of file condition causes termination. The delimiter character is 
extracted. 


istream::ipfx 
int ipfx( int need = 0 ); 


need 
Zero if called from formatted input functions; otherwise the minimum number 
of characters needed. 


This input prefix function is called by input functions prior to extracting data from 
the stream. Formatted input functions call ipfx( 0 ), while unformatted input func- 
tions usually call ipfx( 1 ). 


Any ios object tied to this stream is flushed if need = 0 or if there are fewer than 
need characters in the input buffer. Also, ipfx extracts leading white space if 
i0s::skipws is set. 


Return Value 


See Also 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 


See Also 


istream::istream 881 


A nonzero return value if the operation was successful; 0 if the stream’s error state 
is nonzero, in which case the function does nothing. 


istream: :zisfx 


istream::isfx 


void isfx(); 


This input suffix function is called at the end of every extraction operation. In the 
current implementation, it does nothing, but it may be used in future versions of 
the class library. 


istream::istream 


Public: 
istream( streambuf* psb ); 


Protected: 
istream( ); 


psb 
A pointer to an existing object of a streambuf-derived class. 


Constructs an object of type istream. 


i0S::init 


882 istream::~istream 


Syntax 


Remarks 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 


Syntax 


istream::~istream 


virtual ~istream(); 


Virtual destructor for the istream class. 


istream::peek 


int peek() const; 


Returns the next character without extracting it from the stream. Returns EOF if 
the stream is at end of file or if the ipfx function indicates an error. 


istream::putback 


istream& putback( char ch ); 


ch 
The character to put back; must be the character previously extracted. 


Puts a character back into the input stream. The putback function may fail and set 
the error state. If ch does not match the character that was previously extracted, 
then the result is undefined. 


istream::read 


istream& read( char* pch, int nCount ); 
istream& read( unsigned char* puch, int nCount ); 


istream& read( signed char* psch, int nCount ); 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


istream::seekg 883 


pch, puch, psch 
A pointer to a character array. 


nCount 
The maximum number of characters to read. 


Extracts bytes from the stream until the limit nCount is reached or until the end of 
file 1s reached. The read function is useful for binary stream input. 


istream:: get, istream::getline, istream::gcount, istream::ignore 


istream::seekg 


istream& seekg( streampos pos ); 


istream& seekg( streamoff off, ios::seek_dir dir ); 


pos 

The new position value; streampos is a typedef equivalent to long. 
off 

The new offset value; streamoff is a typedef equivalent to long. 
dir 

The seek direction. Must be one of the following enumerators: 


Value Meaning 

ios: :beg Seek from the beginning of the stream. 
ios::cur Seek from the current position in the stream. 
ios::end Seek from the end of the stream. 


Changes the get pointer for the stream. Not all derived classes of istream need 
support positioning; it is most often used with file-based streams. 


istream::tellg, ostream::seekp, ostream::tellp 


884 istream::sync 


Syntax 


Remarks 


Return Value 


See Also 


Syntax 
Remarks 
Return Value 


See Also 


istream::sync 


int sync(); 


Synchronizes the stream’s internal buffer with the external source of characters. 
This function calls the virtual streambuf::sync function so you can customize its 
implementation by deriving a new class from streambuf. 


EOF to indicate errors. 


streambuf::sync 


istream::tellg 


streampos tellg(); 
Gets the value for the stream’s get pointer. 
A streampos type, corresponding to a long. 


istream::seekg, ostream::tellp, ostream::seekp 


Operators 


Syntax 


Remarks 


istream::operator >> 


istream::operator >> 


istream& operator >>( char* psz ); 

istream& operator >>( unsigned char* pusz ); 
istream& operator >>( signed char* pssz ); 
istream& operator >>( char& rch ); 

istream& operator >>( unsigned char& ruch ); 
istream& operator >>( signed char& rsch ); 
istream& operator >>( short& s ); 

istream& operator >>( unsigned short& us ); 
istream& operator >>( int& n ); 

istream& operator >>( unsigned int& un ); 
istream& operator >>( long& / ); 

istream& operator >>( unsigned long& ul ); 
istream& operator >>( float& f); 

istream& operator >>( double& d ); 

istream& operator >>( long double& /d ); 
istream& operator >>( streambuf* psb ); 
istream& operator >>( istream& (*fcn)(istream&) ); 


istream& operator >>( ios& (*fcn)(ios&) )5 


885 


These overloaded operators extract their argument from the stream. The last two 
variations allow the use of manipulators that are defined for both istream and ios. 


886 istream& ws 


Manipulators 
istream& ws 
Syntax — Ws 
Remarks Extracts leading white space from the stream by calling the eatwhite function. 


See Also istream::eatwhite 


istream_withassign 887 


Class istream_withassign : public istream 


The istream_ withassign class is a variant of istream that allows object assign- 
ment. The predefined object cin is an object of this class and thus may be reas- 
signed at run time to a different istream object. 


A program that normally expects input from stdin, for example, could be tem- 
porarily directed to accept its input from a disk file. 


Predefined Objects The cin object is a predefined object of class ostream_ withassign. It is connected 
to stdin (standard input, file descriptor 0). 


The objects cin, cerr, and clog are tied to cout so that use of any of these may 
cause cout to be flushed. 


#include <iostream.h> 


See Also ostream_ withassign 


Public Members 


Construction/Destruction 


istream_ withassign Constructs an istream_ withassign object. 
~istream_ withassign Destroys an istream_ withassign object. 
Operators 


operator = Indicates an assignment operator. 


888 istream_withassign::istream_withassign 


Member Functions 


Syntax 


Parameters 


Remarks 


See Also 


syntax 


Remarks 


istream_withassign::istream_withassign 


istream_ withassign( streambuf* psb ); 


istream_ withassign(); 


psb 
A pointer to an existing object of a streambuf-derived class. 


The first constructor creates a ready-to-use object of type istream_ withassign, 
complete with attached streambuf object. 


The second constructor creates an object but does not initialize it. You must sub- 
sequently use the second variation of the istream_ withassign assignment opera- 
tor to attach the streambuf object, or you must use the first variation to initialize 
this object to match the specified istream object. 


istream_withassign::operator = 


istream_withassign::~istream_withassign 


~istream_ withassign(); 


Destructor for the istream_ withassign class. 


Operators 


Syntax 


Remarks 


Example 1 


Example 2 


See Also 


istream_withassign::operator = 889 


istream_withassign::operator = 


istream& operator =( const istream& ris ); 


istream& operator =( streambuf* psb ); 


The first overloaded assignment operator assigns the specified istream object to 
this istream_ withassign object. 


The second operator attaches a streambuf object to an existing 

istream_ withassign object, and it initializes the state of the istream_ withassign 
object. This operator is often used in conjunction with the void-argument 
constructor. 


char buffer[100]; 
class xistream; // A special-purpose class derived from istream 
extern xistream xin; // An xistream object constructed elsewhere 


cin = xin; // cin is reassigned to xin 
cin >> buffer; // xin used instead of cin 


char buffer[10Q]; 
extern filedesc fd; // A file descriptor for an open file 
filebuf fb( fd ); // Construct a filebuf attached to fd 


cin = &fb; // fb associated with cin 
cin >> buffer; // cin now gets its intput from the fb file 


istream_ withassign::istream_ withassign, cin 


890 


class istrstream : public istream 


See Also 


Public Members 


The istrstream class supports input streams that have character arrays as a source. 
You must allocate a character array prior to the construction of an istrstream ob- 
ject. All the istream operators and functions (including seeking) can then be used 
on this character data. 


You must be aware that there is a get pointer working behind the scenes in the 
attached strstreambuf class. This pointer advances as you extract fields from 
the stream’s array. The only way you can make it go backwards is to use the 
istream::seekg function. If the get pointer reaches the end of the string (and 
sets the 1os::eof flag), then you must call clear before seekg. 


#include <strstrea.h> 


strstreambuf, streambuf, strstream, ostrstream 


Construction/Destruction 


istrstream Constructs an istrstream object. 

~istrstream Destroys an istrstream object. 

Other Functions 

rdbuf Returns a pointer to the stream’s associated 
strstreambuf object. 

str Returns a character array pointer to the string 


stream’s contents. 


istrstream::~istrstream 891 


Member Functions 


Syntax 


Parameters 


Remarks 


Syntax 


Remarks 


istrstream::istrstream 


istrstream( char* psz ); 


istrstream( char* pch, int nLength ); 


PSZ 
A null-terminated character array (string). 
pch 
A character array that is not necessarily null terminated. 


nLength 
The size (in characters) of pch. If 0, then pch is assumed to point to a null- 
terminated array; if less than O, then the array is assumed to have unlimited 
length. 


The first constructor uses the specified psz buffer to make an istrstream object 
with length corresponding to the string length. 


The second constructor makes an istrstream object out of the first nLength charac- 
ters of the pch buffer. 


Both constructors automatically construct a strstreambuf object that manages the 
specified character buffer. 


istrstream::~istrstream 


~istrstream(); 


Destroys an istrstream object and its associated strstreambuf object. The charac- 
ter buffer is not released because it was allocated by the user prior to istrstream 
construction. 


892 istrstream::rdbuf 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


istrstream::rdbuf 


strstreambuf* rdbuf() const; 
Returns a pointer to the strstreambuf buffer object that is associated with this 
stream. Note that this is not the character buffer itself; the strstreambuf object 


contains a pointer to the character area. 


istrstream::str 


istrstream::str 


char* str(); 


Returns a pointer to the string stream’s character array. This pointer corresponds 
to the array used to construct the istrstream object. 


istrstream::istrstream 


ofstream 893 


class ofstream : public ostream 


The ofstream class is an ostream derivative specialized for disk file output. All of 
its constructors automatically create and associate a filebuf buffer object. 


The filebuf class documentation describes the get and put areas and their as- 
sociated pointers. Only the put area and the put pointer are active for the ofstream 
class. 


#include <fstream.h> 


See Also filebuf, streambuf, ifstream, fstream 


Public Members 


Construction/Destruction 


ofstream Constructs an ofstream object. 

~ofstream Destroys an ofstream object. 

Operations 

open Opens a file and attaches it to the filebuf object 
and thus to the stream. 

close Flushes any waiting output and closes the 
stream’s file. 

setbuf Associates the specified reserve area to the 
stream’s filebuf object. 

setmode Sets the stream’s mode to binary or text. 

attach Attaches the stream (through the filebuf object) to 
an open file. 

Status/Information 

rdbuf Gets the stream’s filebuf object. 

fd Returns the file descriptor associated with the 


is_open 


stream. 


Tests whether the stream’s file is open. 


894 ofstream::attach 


Member Functions 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


ofstream::attach 


void attach( filedesc fd ); 


Jd 
A file descriptor as returned by a call to the run-time function _ open or 
_sopen; filedesc is a typedef equivalent to int. 


Attaches this stream to the open file specified by fd. The function fails when the 
stream is already attached to a file. In that case, the function sets ios::failbit in the 


stream’s error State. 


filebuf::attach, ofstream::fd 


ofstream::close 


void closeQ); 
Calls the close member function for the associated filebuf object. This function, in 


turn, flushes any waiting output, closes the file, and disconnects the file from the 
filebuf object. The filebuf object is not destroyed. 


The stream’s error state is cleared unless the call to filebuf::close fails. 


filebuf::close, ofstream::open, ofstream::is_ open 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


Syntax 


ofstream::ofstream 895 


ofstream::fd 
filedesc fd() const; 


Returns the file descriptor associated with the stream. filedesc is a typedef equiv- 
alent to int. Its value is supplied by the underlying file system. 


filebuf::fd, ofstream::attach 


ofstream::is_ open 


int is_open() const; 


Returns a nonzero value if this stream is attached to an open disk file identified by 
a file descriptor; otherwise 0. 


filebuf::is_open, ofstream::open, ofstream::close 


ofstream::ofstream 


ofstream(); 


ofstream( const char* szName, int nMode = ios::out, 
int nProt = filebuf::openprot ); 


ofstream( filedesc fd ); 


ofstream( filedesc fd, char* pch, int nLength ); 


896 ofstream::ofstream 


Parameters szName 
The name of the file to be opened during construction. 


nMode 
An integer that contains mode bits defined as ios enumerators that can be com- 
bined with the bitwise-OR (| ) operator: 


Value Meaning 


ios::app The function performs a seek to the end of file. When 
new bytes are written to the file, they are always 
appended to the end, even if the position is moved with 
the ostream::seekp function. 


ios::ate The function performs a seek to the end of file. When 
the first new byte is written to the file, it is appended to 
the end, but when subsequent bytes are written, they are 
written to the current position. 


ios::in If this mode is specified, then the original file (if it 
exists), will not be truncated. 

ios::out The file 1s opened for output (implied for all ofstream 
objects). 

ios::trunc If the file already exists, its contents are discarded. This 


mode is implied if ios::out is specified and ios::ate, 
i0S::app, and ios:in are not specified. 


ios::nocreate If the file does not already exist, the function fails. 

ios::noreplace If the file already exists, the function fails. 

ios::binary Opens the file in binary mode (the default is text mode). 
nProt 


The file protection specification; defaults to the static integer filebuf::openprot 
that is equivalent to filebuf::sh_ compat. The possible nProt values are: 


Value Meaning 


filebuf::sh_ compat Compatibility share mode. 


filebuf::sh_none Exclusive mode; no sharing. 
filebuf::sh_read Read sharing allowed. 
filebuf::sh_ write Write sharing allowed. 


The filebuf::sh_ read and filebuf::sh_ write modes can be combined with the 
logical OR (I ) operator. 


Remarks 


Syntax 


Remarks 


fa 


ofstream::~ofstream 


A file descriptor as returned by a call to the run-time function _ open or 
_sopen. filedesc is a typedef equivalent to int. 


pch 
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Pointer to a previously allocated reserve area of length nLength. A NULL value 
(or nLength = 0) indicates that the stream will be unbuffered. 


nLength 


The length (in bytes) of the reserve area (0 = unbuffered). 


The four ofstream constructors are described as follows: 


Constructor 


ofstream() 


ofstream( const char’, int, int ) 


ofstream( filedesc ) 


ofstream( filedesc, char*, int ) 


Description 


Constructs an ofstream object without 
opening a file. 


Contructs an ofstream object, opening 
the specified file. 


Constructs an ofstream object that is 
attached to an open file. 


Constructs an ofstream object that is 
associated with a filebuf object. The 
filebuf object is attached to an open 
file and to a specified reserve area. 


All ofstream constructors construct a filebuf object. The first three use an inter- 
nally allocated reserve area, but the fourth uses a user-allocated area. The user- 
allocated area is not automatically released during destruction. 


ofstream::~ofstream 


~ofstream(); 


Flushes the buffer, then destroys an ofstream object along with its associated 
filebuf object. The file is closed only if was opened by the constructor or by the 


open member function. 


The filebuf destructor releases the reserve buffer only if it was internally allocated. 


898 ~—Ss« Of Stream::open 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


Example 


ofstream::open 


void open( const char* szName, int nMode = ios::out, 
int Prot = filebuf::openprot ); 


szName 
The name of the file to be opened during construction. 


nMode 
An integer containing mode bits defined as ios enumerators that can be com- 
bined with the OR (| ) operator. See the ofstream constructor for a list of the 
enumerators. The tos::out mode is implied. 


nProt 
The file protection specification; defaults to the static integer 
filebuf::openprot. See the ofstream constructor for a list of the other allowed 
values. 


Opens a disk file and attaches it to the stream’s filebuf object. If the filebuf object 
is already attached to an open file, or if a filebuf call fails, the ios::failbit is set. If 
the file is not found, then the ios::failbit is set only if the ios::nocreate mode was 
used. 


filebuf::open, ofstream::ofstream, ofstream::close, ofstream::is_ open 


ofstream::rdbuf 
filebuf* rdbufQ const; 


Returns a pointer to the filebuf buffer object that is associated with this stream. 
(Note that this is not the character buffer; the filebuf object contains a pointer to 
the character area.) | 


extern ofstream ofs; | 
int fd = ofs.rdbuf()->fd(); // Get the file descriptor for ofs 


Syntax 


Parameters 


Remarks 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


ofstream::setmode 899 


ofstream::setbuf 


streambuf* setbuf( char* pch, int nLength ); 


pch 
A pointer to a previously allocated reserve area of length nLength. ANULL 
value indicates an unbuffered stream. 


nLength 
The length (in bytes) of the reserve area. A length of 0 indicates an unbuffered 
stream. 


Attaches the specified reserve area to the stream’s filebuf object. If the file is open 
and a buffer has already been allocated, the function returns NULL; otherwise it 
returns a pointer to the filebuf cast as a streambuf. The reserve area will not be re- 
leased by the destructor. 


ofstream::setmode 


int setmode( int nMode = filebuf::text ); 


nMode 
An integer that must be one of the static filebuf constants, as follows: 
Value Meaning 
filebuf: :text Text mode (newline characters translated to and from . 


carriage return—linefeed pairs). 


filebuf: :binary Binary mode (no translation). 


This function sets the binary/text mode of the stream’s filebuf object. It may be 
called only after the file is opened. 


The previous mode; —1 if the parameter is invalid, the file is not open, or the mode 
cannnot be changed. 


ios binary manipulator, ios text manipulator 


900 ostream 


class ostream : virtual public tos 


Derivation 


See Also 


The ostream class provides the basic capability for sequential and random-access 
output. An ostream object has a streambuf-derived object attached, and the two 

classes work together; the ostream class does the formatting, and the streambuf 

class does the low-level buffered output. 


You can use ostream objects for sequential disk output if you first construct an 
appropriate filebuf object. (The filebuf class is derived from streambuf.) More 
often, you will use the predefined stream objects cout, cerr, and clog (actually ob- 
jects of class ostream_ withassign), or you will use objects of classes ofstream 
(disk file streams) and ostrstream (string streams). 


All of the ostream member functions write unformatted data; formatted output is 
handled by the insertion operators. 


It is not always necessary to derive from ostream to add functionality to a stream; 
consider deriving from streambuf instead, as illustrated in Chapter 19 of the Class 
Libraries User’s Guide. The ofstream and ostrstream classes are examples of 
ostream-derived classes that construct member objects of predetermined derived 
streambuf classes. 


You can add manipulators without deriving a new class. 


If you add new insertion operators for a derived ostream class, then the rules of 
C++ dictate that you must reimplement all the base class insertion operators. If, 
however, you reimplement the operators through inline equivalence, no extra code 
will be generated. For example, 


class xstream : public ostream 


{ 
public: 
// Constructors, etc. 
Vee tue 
inline xstream& operator << ( char ch ) // insertion for char 
1 
return (xstream&)ostream::operator << ( ch ); 
} 
Lb eS erers tase 
// Insertions for other types 
}; 


#include <iostream.h> 


streambuf, ofstream, ostrstream, cout, cerr, clog 


Public Members 


Manipulators 


Construction/Destruction 


ostream 


~ostream 


Prefix/Suffix Functions 
opfx 


osfx 


Unformatted Output 
put 


write 


Other Functions 
flush 

seekp 

tellp 


Operators 
operator << 


endl 
ends 
flush 


ostream 901 


Constructs an ostream object that is attached to an 
existing streambuf object. 


Destroys an ostream object. 


Output prefix function, called prior to insertion 
operations to check for error conditions, and so 
forth. 


Output suffix function, called after insertion opera- 
tions; flushes the stream’s buffer if it 1s unit 
buffered. 


Inserts a single byte into the stream. 


Inserts a series of bytes into the stream. 


Flushes the buffer associated with this stream. 
Changes the stream’s put pointer. 


Gets the value of the stream’s put pointer. 


An insertion operator for various types. 


Inserts a newline sequence and flushes the buffer. 
Inserts a null character to terminate a string. 


Flushes the stream’s buffer. 


902 ostream::flush 


Member Functions 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


Return Value 


Syntax 


Remarks 


ostream::flush 


ostream& flush(); 


Flushes the buffer associated with this stream. The flush function calls the syne 
function of the associated streambuf. 


ostream flush manipulator, streambuf::syne 


ostream::opfx 
int opfxQ; 


This output prefix function is called before every insertion operation. If another 
ostream object is tied to this stream then the opfx function flushes that stream. 


If the ostream object’s error state is not 0, opfx returns 0 immediately; otherwise 
it returns a nonzero value. 


ostream::osfx 


void osfxQ); 


This output suffix function is called after every insertion operation. It flushes 
the ostream object if ios::unitbuf is set. It flushes stdout and stderr if ios::stdio 
1s set. 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 


ostream::put 903 


ostream::ostream 


Public: 
ostream( streambuf* psb ); 


Protected: 
ostream( ); 


psb 
A pointer to an existing object of a streambuf-derived class. 


Constructs an object of type ostream. 


ios::init 


ostream::~ostream 


virtual ~ostream(); 


Destroys an ostream object. The output buffer is flushed as appropriate. The at- 
tached streambuf object is destroyed only if it was allocated internally within the 
ostream constructor. 


ostream::put 


ostream& put( char ch ); 


ch 
The character to insert. 


This function inserts a single character into the output stream. 


904 ostream::seekp 


ostream::seekp 


Syntax ostream& seekp( streampos pos ); 


ostream& seekp( streamoff off, ios::seek_ dir dir ); 


Parameters pos 
The new position value; streampos is a typedef equivalent to long. 
off 
The new offset value; streamoff is a typedef equivalent to long. 
dir 
The seek direction specified by the enumerated type ios::seek_ dir, as follows: 
Value Meaning 
ios::beg Seek from the beginning of the stream. 
ios::cur Seek from the current position in the stream. 
ios::end Seek from the end of the stream. 
Remarks Changes the position value for the stream. Not all derived classes of ostream need 


support positioning. For file streams, the position is the byte offset from the begin- 
ning of the file; for string streams, it is the byte offset from the beginning of the 
string. 


See Also ostream::tellp, istream::seekg, istream::tellg 


ostream::tellp 


syntax streampos tellpQ; 


Remarks Gets the position value for the stream. Not all derived classes of ostream need sup- 
port positioning. For file streams, the position is the byte offset from the beginning 
of the file; for string streams, it is the byte offset from the beginning of the string. 
Gets the value for the stream’s put pointer. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


ostream::write 905 


A streampos type that corresponds to a long. 


ostream::seekp, istream::tellg, istream::seekg 


ostream::write 


ostream& write( const char* pch, int nCount ); 
ostream & write( const unsigned char* puch, int nCount ); 


ostream & write( const signed char* psch, int nCount ); 


pch, puch, psch 
A pointer to a character array. 


nCount 
The number of characters to be written. 


Inserts a specified number of bytes from a buffer into the stream. If the underlying 
file was opened in text mode, additional carriage return characters may be in- 
serted. The write function is useful for binary stream output. 


906 ostream::operator << 


Operators 


ostream::operator << 


Syntax ostream& operator <<( char ch ); 
ostream& operator <<( unsigned char uch ); 
ostream& operator <<( signed char sch ); 
ostream& operator <<( const char* psz ); 
ostream& operator <<( const unsigned char *pusz ); 
ostream& operator <<( const signed char *pssz ); 
ostream& operator <<( short s ); 
ostream& operator <<( unsigned short us ); 
ostream& operator <<( int 7 ); 
ostream& operator <<( unsigned int un ); 
ostream& operator <<( long / ); 
ostream& operator <<( unsigned long wl ); 
ostream& operator <<( float f); 
ostream& operator <<( double d ); 
ostream& operator <<( long double /d ); 
ostream& operator <<( void* pv ); 
ostream& operator <<( streambuf* psb ); 
ostream& operator <<( ostream& (*fcn)(ostream&) ); 


ostream& operator <<(ios& (*fcn)(ios&) ); 


Remarks These overloaded operators insert their argument into the stream. The last two var- 
iations allow the use of manipulators that are defined for both ostream and ios. 


ostream& flush 907 


Manipulators 


Syntax 


Remarks 


Syntax 


Remarks 


Syntax 


Remarks 


See Also 


ostreamé& endl 


endl 


This manipulator, when inserted into an output stream, inserts a newline character 
and then flushes the buffer. 


ostream& ends 


ends 


This manipulator, when inserted into an output stream, inserts a null-terminator 
character. It is particularly useful for ostrstream objects. 


ostream& flush 


flush 


This manipulator, when inserted into an output stream, flushes the output buffer 
by calling the streambuf::sync member function. 


ostream::flush, streambuf::syne 


908 ostream_withassign 


class ostream_withassign : public ostream 


Predefined 
Objects 


See Also 


Public Members 


The ostream_withassign class is a variant of ostream that allows object assign- 
ment. The predefined objects cout, cerr, and clog are objects of this class and thus 
may be reassigned at run time to a different ostream object. 


A program that normally sends output to stdout, for example, could be tem- 
porarily directed to send its output to a disk file. 


There are three predefined objects of class ostream_ withassign. They are con- 
nected as follows: 


cout 
Standard output (file descriptor 1). 


cerr 
Unit buffered standard error (file descriptor 2). 


clog 
Fully buffered standard error (file descriptor 2). 


Unit buffering, as used by cerr, means that characters are flushed after each inser- 


tion operation. The objects cin, cerr, and clog are tied to cout so that use of any of 
these will cause cout to be flushed. 


#include <iostream.h> 


istream_ withassign 


Construction/Destruction 


ostream_ withassign Constructs an ostream_ withassign object. 
~ostream_ withassign Destroys an ostream_ withassign object. 
Operators 


operator = Assignment operator. 


ostream_withassign::~ostream_withassign 909 


Member Functions 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


ostream_withassign::ostream_withassign 


ostream_ withassign( streambuf* psb ); 


ostream_ withassign(); 


psb 
A pointer to an existing object of a streambuf-derived class. 


The first constructor makes a ready-to-use object of type ostream_ withassign, 
complete with an attached streambuf object. 


The second constructor makes an object but does not initialize it. You must sub- 
sequently use the streambuf assignment operator to attach the streambuf object, 
or you must use the ostream assignment operator to initialize this object to match 
the specified object. 


ostream_ withassign::operator = 


ostream_withassign::~ostream_withassign 


~ostream_ withassign(); 


Destructor for the ostream_ withassign class. 


910 ostream_withassign::operator = 


Operators 


Syntax 


Remarks 


Example 


See Also 


ostream_withassign::operator = 


ostream& operator =( ostream& ros ); 


ostream& operator =( streambuf* sbp ); 


The first overloaded assignment operator assigns the specified ostream object to 
this ostream_ withassign object. 


The second operator attaches a streambuf object to an existing 

ostream_ withassign object, and it initializes the state of the ostream_ withassign 
object. This operator is often used in conjunction with the void-argument 
constructor. 


filebuf fb( "test.dat" ); // Filebuf object attached to "“test.dat" 
cout = &fb; // fb associated with cout 
cout << "testing"; // Message goes to "test.dat" instead of stdout 


ostream_ withassign::ostream_ withassign, cout 


ostrstream 911 


class ostrstream : public ostream 


The ostrstream class supports output streams that have character arrays as a desti- 
nation. You can allocate a character array prior to construction, or the constructor 
can internally allocate an expandable array. All the ostream operators and func- 
tions can then be used to fill the array. 


You must be aware that there is a put pointer working behind the scenes in the 
attached strstreambuf class. This pointer advances as you insert fields into the 
stream’s array. The only way you can make it go backwards is to use the 
ostream::seekp function. If the put pointer reaches the end of user-allocated 
memory (and sets the ios::eof flag), then you must call clear before seekp. 


#include <strstrea.h> 


See Also strstreambuf, streambuf, strstream, istrstream 


Public Members 


Construction/Destruction 


ostrstream Constructs an ostrstream object. 

~ostrstream Destroys an ostrstream object. 

Other Functions 

pcount Returns the number of bytes that have been stored 
in the stream’s buffer. 

rdbuf Returns a pointer to the stream’s associated 
strstreambuf object. 

str Returns a character array pointer to the string 


stream’s contents and freezes the array. 


912 ostrstream::ostrstream 


Member Functions 


Syntax 


Parameters 


Remarks 


ostrstream::ostrstream 


ostrstream(); 


ostrstream( char* pch, int nLength, int nMode = ios::out ); 


pch 
A character array that is large enough to accommodate future output stream 
activity. 


nLength | 
The size (in characters) of pch. If 0, then pch is assumed to point to a null- 
terminated array and strlen( pch ) is used as the length; if less than 0, then the 
array is assumed to have infinite length. 


nMode 
The stream-creation mode. Must be one of the following enumerators as de- 
fined in class ios: 


Value Meaning 
ios::out Default; storing begins at pch 
ios::ate The pch parameter is assumed to be a null-terminated array; 


storing begins at the NULL character 


i0S::app Same as ios::ate 


The first constructor makes an ostrstream object that uses an internal, dynamic 
buffer. 


The second constructor makes an ostrstream object out of the first nLength char- 
acters of the pch buffer. The stream will not accept characters once the length 
reaches nLength. 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


Syntax 


Remarks 


See Also 
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osirstream::~ostrstream 


~ostrstream(); 


Destroys an ostrstream object and its associated strstreambuf object, thus releas- 
ing all internally allocated memory. If you used the void-argument constructor, 
then the internally allocated character buffer is released; otherwise, you must re- 
lease it yourself. 


An internally allocated character buffer will not be released if it was previously 
frozen by an str or strstreambuf::freeze function call. 


ostrstream::str, strstreambuf::freeze 


ostrstream::pcount 


int pcount() const; 


Returns the number of bytes that have been stored in the buffer. This information 
is especially useful when you have stored binary data in the object. 


ostrstream::rdbuf 


strstreambuf* rdbuf() const; 
Returns a pointer to the strstreambuf buffer object that is associated with this 
stream. Note that this is not the character buffer; the strstreambuf object contains 


a pointer to the character area. 


ostrstream::str 


914 osirstream::str 


osirstream::str 


Syntax char* str(Q); 


Remarks Returns a pointer to the internal character array. If the stream was built with the 
void-argument constructor, then str freezes the array. You must not send charac- 
ters to a frozen stream, and you are responsible for deleting the array. You can, 
however, subsequently unfreeze the array by calling rdbuf->freeze( 0 ). 


If the stream was built with the constructor that specified the buffer, then the 
pointer contains the same address as the array used to construct the ostrstream 
object. | 


See Also ostrstream::ostrstream, ostrstream::rdbuf, strstreambuf::freeze 
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class stdiobuf : public streambuf 


See Also 


Public Members 


The run-time library supports three conceptual sets of I/O functions: iostreams 
(C++ only), standard I/O (the functions declared in STDIO.H), and low-level 
I/O (the functions declared in IO.H). The stdiobuf class is a derived class of 
streambuf that is specialized for buffering to and from the standard I/O system. 


Because the standard I/O system does its own internal buffering, the extra buffer- 
ing level provided by stdiobuf may reduce overall input/output efficiency. The 
stdiobuf class is useful when you need to mix iostream I/O with standard I/O 
(printf and so forth). 


You can avoid use of the stdiobuf class if you use the filebuf class. You must also 
use the stream class’s ios::flags member function to set the ios::stdio format flag 
value. 


#include <stdiostr.h> 


stdiostream, filebuf, strstreambuf, ios::flags 


Construction/Destruction 


stdiobuf Constructs a stdiobuf object from a FILE pointer. 
~stdiobuf Destroys a stdiobuf object. 
Other Functions 


stdiofile Gets the file that is attached to the stdiofile object. 


916 stdiobuf::stdiobuf 


Member Functions 


Stdiobuf::stdiobuf 


Syntax stdiobuf( FILE* fp ); 


Parameters Ip 
A standard I/O file pointer (can be obtained through an fopen or _ fsopen call). 


Remarks Objects of class stdiobuf are constructed from open standard I/O files, including 
stdin, stdout, and stderr. The object is unbuffered by default. 


stdiobuf::~stdiobuf 


Syntax ~stdiobuf(); 


Remarks Destroys a stdiobuf object and, in the process, flushes the put area. The destructor 
does not close the attached file. 


stdiobuf::stdiofile 


Syntax FILE* stdiofileQ); 


Remarks Returns the standard I/O file pointer associated with a stdiobuf object. 


stdiostream 917 


Class stdiostream : public iostream 


See Also 


Public Members 


The stdiostream class makes I/O calls (through the stdiobuf class) to the standard 
I/O system, which does its own internal buffering. Calls to the functions declared 
in STDIO.H, such as printf, can be mixed with stdiostream I/O calls. 


This class is included for compatibility with earlier stream libraries. You can avoid 
use of the stdiostream class if you use the ostream or istream class with an as- 
sociated filebuf class. You must also use the stream class’s ios::flags member 
function to set the ios::stdio format flag value. 


The use of the stdiobuf class may reduce efficiency because it imposes an extra 
level of buffering. Do not use this feature unless you need to mix iostream library 
calls with standard I/O calls for the same file. 


#include <stdiostr.h> 


stdiobuf, ios::flags 


Construction/Destruction 


stdiostream Constructs a stdiostream object that is associated 
with a standard I/O FILE pointer. 

~stdiostream Destroys a stdiostream object (virtual). 

Other Functions 


rdbuf Gets the stream’s stdiobuf object. 


918 stdiostream::rdbuf 


Member Functions 


Syntax 


Remarks 


Syntax 


Parameters 


Remarks 


Example 


Syntax 


Remarks 


stdiostream::rdbuf 
stdiobuf* rdbuf() const; 


Returns a pointer to the stdiobuf buffer object that is associated with this stream. 
The rdbuf function is useful when you need to call stdiobuf member functions. 


stdiostream::stdiostream 


stdiostream( FILE* fp ); 


IP 


A standard I/O file pointer (can be obtained through an fopen or _fsopen call). 
Could be stdin, stdout, or stderr. 


Objects of class stdiostream are constructed from open standard I/O files. An un- 
buffered stdiobuf object is automatically associated, but the standard I/O system 
provides its own buffering. | 


stdiostream myStream( stdout ); 


stdiostream::~stdiostream 


virtual ~stdiostream(); 


This destructor destroys the stdiobuf object associated with this stream; however, 
the attached file is not closed. 


streambuf 919 


class streambuf 


All the iostream classes in the ios hierarchy depend on an attached streambuf 
class for the actual I/O processing. This class is an abstract class, but the iostream 
class library contains the following derived buffer classes for use with streams: 


filebuf 
Buffered disk file I/O. 


strstreambuf 
Stream data held entirely within an in-memory byte array. 


stdiobuf 
Disk I/O with buffering done by the underlying standard I/O system. 


All streambuf objects, when configured for buffered processing, maintain a fixed 
memory buffer, called a reserve area, that can be dynamically partitioned into a 
get area for input and a put area for output. These areas may or may not overlap. 
Protected member functions allow access and manipulation of a get pointer for 
character retrieval and a put pointer for character storage. The exact behavior of 
the buffers and pointers depends on the implementation of the derived class. 


The capabilities of the iostream classes can be extended significantly through the 
derivation of new streambuf classes. The ios class tree supplies the programming 
interface and all formatting features, but the streambuf class does the real work. 
The ios classes call the streambuf public members, including a set of virtual 
functions. 


The streambuf class provides a default implementation of certain virtual member 
functions. The “Default Implementation” section for each such function suggests 
function behavior for the derived class. | 


#include <iostream.h> 


Public Members 


Character Input Functions 


in_ avail Returns the number of characters in the get area. 

sgetc Returns the character at the get pointer, but does 
not move the pointer. 

snextc Advances the get pointer, and then returns the next 
character. 

sbumpc Returns the current character, and then advances 


the get pointer. 
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stossc 


sputbackc 


sgetn 


Moves the get pointer forward one position, but 
does not return a character. 


Attempts to move the get pointer back one position. 


Gets a sequence of characters from the streambuf 
object’s buffer. 


Character Output Functions 


out_ waiting 


sputc 


sputn 


Diagnostic Functions 
dbp 


Virtual Functions 
sync 
setbuf 


seekoff 
seekpos 
overflow 
underflow 
pback fail 


Protected Members 


Construction/Destruction 
streambuf 


~streambuf 


Returns the number of characters in the put area. 


Stores a character in the put area and advances the 
put pointer. 


Stores a sequence of characters in the streambuf 
object’s buffer and advances the put pointer. 


Prints buffer statistics and pointer values. 


Empties the get area and the put area. 


Attempts to attach a reserve area to the streambuf 
object. 


Seeks to a specified offset. 
Seeks to a specified position. 
Empties the put area. 

Fills the get area if necessary. 


Augments the sputbackc function. 


Constructors for use in derived classes. 


Virtual destructor. 
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Other Protected Member Functions 


base Returns a pointer to the start of the reserve area. 
ebuf Returns a pointer to the end of the reserve area. 
blen Returns the size of the reserve area. 

pbase Returns a pointer to the start of the put area. 
pptr Returns the put pointer. 

epptr Returns a pointer to the end of the put area. 
eback Returns the lower bound of the get area. 

eptr Returns the get pointer. 

egptr Returns a pointer to the end of the get area. 

setp Sets all the put area pointers. 

setg Sets all the get area pointers. 

pbump Increments the put pointer. 

gbump Increments the get pointer. 

setb Sets up the reserve area. 

unbuffered Tests or sets the streambuf buffer state variable. 
allocate Allocates a buffer, if needed, by calling doalloc. 


doallocate Allocates a reserve area (virtual function). 
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streambuf::allocate 


Member Functions 


Syntax 


Remarks 


See Also 


syntax 


Remarks 


See Also 


syntax 


Remarks 


See Also 


streambut::allocate 


Protected: 
int allocate(); 


Calls the virtual function doallocate to set up a reserve area. If a reserve area al- 
ready exists or if the streambuf object is unbuffered, allocate returns 0. If the 
space allocation fails, allocate returns EOF. 


streambuf::doallocate, streambuf::unbuffered 


streambuf::base 


Protected: 
char* base() const; 


Returns a pointer to the first byte of the reserve area. The reserve area consists of 
space between the pointers returned by base and ebuf. 


streambuf::ebuf, streambuf::setb, streambuf::blen 


streambuf::blen 


Protected: 
int blen() const; 


Returns the size, in bytes, of the reserve area. 


streambuf::base, streambuf::ebuf, streambuf::setb 


streambuf::doallocate 923 


streambuf::dbp 
Syntax void dbpQ); 


Remarks Writes ASCII debugging information directly on stdout. Treat this function as 
part of the protected interface. 


Some sample output follows: 


STREAMBUF DEBUG INFO: this = @Q0E7:09DC, _fAlloc=1 
base()=@@E7:@AQC, ebuf()=@0E7:0C@C, blen()=512 

pbase()=Q0E7:@A@C, pptr()=Q0E7:0A22, epptr( )=00E7:0COC 
eback()=0000:0000, gptr()=0000:0000, egptr( )=0000: 0000 


streambuf::doallocate 


Syntax Protected: 
virtual int doallocateQ); 


Remarks Called by allocate when space is needed. The doallocate function must allocate a 
reserve area, then call setb to attach the reserve area to the streambuf object. If 
the reserve area allocation fails, doallocate returns EOF. 


Default Attempts to allocate a reserve area using operator new. 
Implementation 


See Also streambuf::allocate, streambuf::setb 


924 streambuf::eback 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


syntax 


Remarks 


See Also 


streambuf::eback 


Protected: 
char* eback() const; 


Returns the lower bound of the get area. Space between the eback and gptr point- 
ers 1s available for putting a character back to the stream. 


streambuf::sputbackc, streambuf::gptr 


streambuf::ebuf 


Protected: 
char* ebuf() const; 


Returns a pointer to the byte after the last byte of the reserve area. The reserve 
area consists of space between the pointers returned by base and ebuf. 


streambuf::base, streambuf::setb, streambuf::blen 


streambuf::egptr 


Protected: 
char* egptr() const; 


Returns a pointer to the byte after the last byte of the get area. 


streambuf: :setg, streambuf::eback, streambuf::gptr 
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streambuf::epptr 


Syntax Protected: 

char* epptr() const; 
Remarks Returns a pointer to the byte after the last byte of the put area. 
See Also streambuf::setp, streambuf::pbase, streambuf::pptr 


streambuf::gbump 


Syntax Protected: 
void gbump( int nCount ); 


Parameters nCount 
The number of bytes to increment the get pointer. May be positive or negative. 


Remarks Increments the get pointer. No bounds checks are made on the result. 


See Also streambuf::pbump 


streambuf::gptr 


Syntax Protected: 
char* gptrQ const; 


Remarks Returns a pointer to the next character to be fetched from the streambuf buffer. 
This pointer is known as the get pointer. 


see Also streambuf::setg, streambuf::eback, streambuf::egptr 


926 streambuf::in_ avail 


Syntax 


Remarks 


Syntax 


Remarks 


syntax 


Parameters 


Remarks 


streambuf::in_ avail 


int in_avail() const; 


Returns the number of characters in the get area that are available for fetching. 
These characters are between the gptr and egptr pointers and may be fetched with 
a guarantee of no errors. 


streambuf::out_waiting 


int out_ waiting() const; 


Returns the number of characters in the put area that have not been sent to the final 
output destination. These characters are between the pbase and pptr pointers. 


streambuft::overflow 


virtual int overflow( int nCh = EOF ) = 90; 


nCh 
EOF or the character to output. 


The virtual overflow function, together with the sync and underflow functions, 
defines the characteristics of the streambuf-derived class. Each derived class 
might implement overflow differently, but the interface with the calling stream 
class 1s the same. 


The overflow function is most frequently called by public streambuf functions 
like sputc and sputn when they sense that the put area is full, but other classes, in- 
cluding the stream classes, can call overflow anytime. 


The function “consumes” the characters in the put area between the pbase and 
pptr pointers and then reinitializes the put area. The overflow function must also 
consume nCh (if nCh is not EOF), or it might choose to put that character in the 
new put area so that it will be consumed on the next call. 


Default 
Implementation 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Default 
[Implementation 


Return Value 


See Also 


streambuf::pbackfail 927 


The definition of “consume” varies among derived classes. The filebuf class, for 
example, writes its characters to a file. The strsteambuf class, on the other hand, 
keeps them in its buffer and (if the buffer is designated as dynamic) expands the 
buffer in response to a call to overflow. This expansion is achieved by freeing the 
old buffer and replacing it with a new, larger one. The pointers are adjusted as 
necessary. 


No default implementation. Derived classes must define this function. 


EOF to indicate an error. 


streambuf::pbase, streambuf::pptr, streambuf::setp, streambuf::sync, 
streambuf::underflow 


streambuf::pbackfail 


virtual int pbackfail( int nCh ); 


nCh 
The character used in a previous sputbackce call. 


This function is called by sputbackc if it fails, usually because the eback pointer 
equals the gptr pointer. The pbackfail function should deal with the situation, if 
possible, by such means as repositioning the external file pointer. 


Returns EOF. 


The nCh parameter if successful; otherwise EOF. 


streambuf::sputbackc 
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Syntax 


Remarks 


See Also 


syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


streambuf::pbase 


Protected: 
char* pbase() const; 


Returns a pointer to the start of the put area. Characters between the pbase pointer 
and the pptr pointer have been stored in the buffer but not flushed to the final out- 
put destination. 


streambuf::pptr, streambuf::setp, streambuf::out_ waiting 


streambuf::pbump 


Protected: 
void pbump( int nCount ); 


nCount 
The number of bytes to increment the put pointer. May be positive or negative. 


Increments the put pointer. No bounds checks are made on the result. 


streambuf::gbump, streambuf::setp 


streambuf::pptr 


Protected: 
char* pptr() const; 


Returns a pointer to the first byte of the put area. This pointer 1s known as the put 
pointer and is the destination for the next character(s) sent to the streambuf object. 


streambuf::epptr, streambuf::pbase, streambuf::setp 


Syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Default 
Implementation 


streambuf::seekoff 929 


streambuf::sbumpc 


int sbumpc(); 


Returns the current character, and then advances the get pointer. Returns EOF if 
the get pointer is currently at the end of the sequence (equal to the egptr pointer). 


streambuf::epptr, streambuf::gbump 


streambuf::seekoff 


virtual streampos seekoff( streamoff off, ios::seek_ dir dir, 
int nMode = ios::in | ios::out ); 


off 
The new offset value; streamoff is a typedef equivalent to long. 
dir 
The seek direction specified by the enumerated type seek_ dir, as follows: 
Value Meaning 
ios: :beg Seek from the beginning of the stream. 
ios::cur Seek from the current position in the stream. 
ios::end Seek from the end of the stream. 
nMode 


An integer that contains a bitwise-OR (| ) combination of the enumerators 
ios::in and ios::out. 


Changes the position for the streambuf object. Not all derived classes of 
streambuf need to support positioning; however, the filebuf, strstreambuf, and 
stdiobuf classes do support positioning. 


Classes derived from streambuf often support independent input and output posi- 
tion values. The nMode parameter determines which value(s) is set. 


Returns EOF. 


930 streambuf::seekpos 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Default 
Implementation 


Return Value 


See Also 


The new position value. This is the byte offset from the start of the file (or string). 
If both ios::in and ios::out are specified, then the function returns the output 
position. If the derived class does not support positioning, then the function 
returns EOF. 


streambuf::seekpos 


streambuf::seekpos 


virtual streampos seekpos( streampos pos, int nMode = ios::in | ios::out ); 


pos 
The new position value; streampos is a typedef equivalent to long. 


~nMode 


An integer that contains mode bits defined as ios enumerators that can be com- 
bined with the OR (|) operator. See ofstream::ofstream for a listing of the 
enumerators. 


Changes the position, relative to the beginning of the stream, for the streambuf 
object. Not all derived classes of streambuf need to support positioning; however, 
the filebuf, strstreambuf, and stdiobuf classes do support positioning. 


Classes derived from streambuf often support independent input and output posi- 
tion values. The nMode parameter determines which value(s) is set. 


Calls seekoff( (streamoff) pos, ios::beg, nMode ). Thus, to define seeking in a 
derived class, it is usually necessary to redefine only seekoff. 


The new position value. If both ios::in and ios::out are specified, then the func- 
tion returns the output position. If the derived class does not support positioning, 
then the function returns EOF. 


streambuf::seekoff 


Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


streambuf::setbuf 931 


streambuf::setb 


Protected: 
void setb( char* pb, char* peb, int nDelete = 0 ); 


pb 

The new value for the base pointer. 
peb 

The new value for the ebuf pointer. 


nDelete 
Flag that controls automatic deletion. If nDelete is not 0, then the reserve area 
will be deleted (1) when the base pointer is changed by another setb call or (2) 
when the streambuf destructor is called. 


Sets the values of the reserve area pointers. If both pb and peb are NULL, then 
there is no reserve area. If pb is not NULL and peb is NULL, then the reserve area 
has a length of 0. 


streambuf:: base, streambuf::ebuf 


streambuf::setbuf 


virtual streambuf* setbuf( char* pr, int nLength ); 


pr 
A pointer to a previously allocated reserve area of length nLength. A NULL 
value indicates an unbuffered stream. 


nLength 
The length Gin bytes) of the reserve area. A length of 0 indicates an unbuffered 
stream. 


Attaches the specified reserve area to the streambuf object. Derived classes may 
or may not use this area. 


932  Streambuf::setg 


Default Accepts the request if there is not a reserved area already. 
Implementation 


Return Value A streambuf pointer if the buffer is accepted; otherwise NULL. 


streambuf::setg 


Syntax Protected: 
void setg( char* peb, char* pg, char* peg ); 


Parameters peb 
The new value for the eback pointer. 


P§ 
The new value for the gptr pointer. 


pes 
The new value for the egptr pointer. 


Remarks Sets the values for the get area pointers. 


See Also streambuf::eback, streambuf::gptr, streambuf::egptr 


Streambuf::setp 


Syntax Protected: 
void setp( char* pp, char* pep ); 


Parameters pp 
The new value for the pbase and pptr pointers. 


pep 
The new value for the epptr pointer. 


streambuf::sgetn 933 


Remarks Sets the values for the put area pointers. 


See Also streambuf::pptr, streambuf::pbase, streambuf::epptr 


streambuf::sgete 


Syntax int sgetc(); 


Remarks Returns the character at the get pointer. The sgetc function does not move the get 
pointer. Returns EOF if there is no character available. 


See Also streambuf::sbumpc, streambuf::sgetn, streambuf::snextc, streambuf::stossc 


streambuf::sgetn 


Syntax int sgetn( char* pch, int nCount ); 


Parameters pch 
A pointer to a buffer that will receive characters from the streambuf object. 


nCount 
The number of characters to get. 


Remarks Gets the nCount characters that follow the get pointer and stores them in the area 
starting at pch. When fewer than nCount characters remain in the streambuf ob- 
ject, sgetn fetches whatever characters remain. The function repositions the get 
pointer to follow the fetched characters. 


Return Value The number of characters fetched. 


See Also streambuf::sbumpc, streambuf::sgetc, streambuf::snextc, streambuf::stossc 
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syntax 


Remarks 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


streambuf::snextc 


int snextc(); 


First tests the get pointer, then returns EOF if it is already at the end of the get 
area. Otherwise, 1t moves the get pointer forward one character and returns the 
character that follows the new position. It returns EOF if the pointer has been 

moved to the end of the get area. 


streambuf::sbumpc, streambuf::sgetc, streambuf::sgetn, streambuf::stossc 


streambuf::sputbacke 


int sputbackc( char ch ); 


ch 
The character to be put back to the streambuf object. 


Moves the get pointer back one position. The ch character must match the charac- 
ter just before the get pointer. 


EOF on failure. 


streambuf::sbumpc, streambuf::pbackfail 


streambuf::sputc 
int spute( int nCh ); 


nCh 
The character to store in the streambuf object. 


Stores a character in the put area and advances the put pointer. 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


Return Value 


See Also 


Syntax 


Remarks 


See Also 


streambuf::stossc 935 


This public function is available to code outside the class, including the classes 
derived from ios. A derived streambuf class can gain access to its buffer directly 
by using protected member functions. 


The number of characters successfully stored; EOF on error. 


streambuf::sputn 


Streambuf::sputn 


int sputn( const char* pch, int nCount ); 


pch 
A pointer to a buffer that contains data to be copied to the streambuf object. 


nCount 
The number of characters in the buffer. 


Copies nCount characters from pch to the streambuf buffer following the put 
pointer. The function repositions the put pointer to follow the stored characters. 


The number of characters stored. This number is usually nCount but could be less 
if an error occurs. 


streambuf::sputc 


streambuf::stossc 


void stossc(); 


Moves the get pointer forward one character. If the pointer is at the end of the get 
area already, the function has no effect. 


streambuf::sbumpc, streambuf::sgetn, streambuf::snextc, streambuf::sgetc 
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Syntax 


Parameters 


Remarks 


See Also 


Syntax 


Remarks 


streambuf::streambuf 


Protected: 
streambuf(); 


Protected: 
streambuf( char* pr, int nLength ); 


pr 
A pointer to a previously allocated reserve area of length nLength. A NULL 
value indicates an unbuffered stream. 


nLength 
The length (in bytes) of the reserve area. A length of 0 indicates an unbuffered 
stream. 


The first constructor makes an uninitialized streambuf object. This object is not 
suitable for use until a setbuf call is made. A derived class constructor usually 
calls setbuf or uses the second constructor. 


The second constructor initializes the streambuf object with the specified reserve 
area or marks it as unbuffered. 


streambuf::setbuf 


streambuf::~streambuf 


Protected: 
virtual ~streambuf(); 


The streambuf destructor flushes the buffer if the stream is being used for output. 


Syntax 


Remarks 


Default 
Implementation 


Return Value 


See Also 


Syntax 


Parameters 


Remarks 


See Also 


streambuf::unbuffered 937 


streambuf::sync 


virtual int sync(); 


The virtual syne function, together with the overflow and underflow functions, 
defines the characteristics of the streambuf-derived class. Each derived class 
might implement sync differently, but the interface with the calling stream class is 
the same. 


The sync function flushes the put area. It also empites the get area and, in the 
process, sends any unprocessed characters back to the source, if necessary. 


Returns 0 if the get area is empty and there are no more characters to output; other- 
wise, it returns EOF. 


EOF if an error occurs. 


streambuf::overflow 


streambuf::unbuffered 


Protected: 
void unbuffered( int nState ); 


Protected: 
int unbuffered() const; 


nState 
The value of the buffering state variable; 0 = buffered, nonzero = unbuffered. 


The first overloaded unbuffered function sets the value of the streambuf object’ s 
buffering state. This variable’s primary purpose is to control whether the allocate 
function automatically allocates a reserve area. 


The second function returns the current buffering state variable. 


streambuf::allocate, streambuf::doallocate 


938 streambuf::underflow 


Syntax 


Remarks 


Default 
Implementation 


streambuf::underflow 


virtual int underflow() = 0; 


The virtual underflow function, together with the sync and overflow functions, 
defines the characteristics of the streambuf-derived class. Each derived class 
might implement underflow differently, but the interface with the calling stream 
class is the same. 


The underflow function is most frequently called by public streambuf functions 
like sgetc and sgetn when they sense that the get area is empty, but other classes, 
including the stream classes, can call underflow anytime. 


The underflow function supplies the get area with characters from the input 
source. If the get area contains characters, then underflow returns the first charac- 
ter. If the get area is empty, then it fills the get area and returns the next character 
(which it leaves in the get area). If there are no more characters available, then 
underflow returns EOF and leaves the get area empty. 


In the strstreambuf class, underflow adjusts the egptr pointer to access storage 
that was dynamically allocated by a call to overflow. 


No default implementation. Derived classes must define this function. 


Strstream 939 


class strstream : public iostream 


See Also 


Public Members 


The strstream class supports I/O streams that have character arrays as a source 
and destination. You can allocate a character array prior to construction, or the con- 
structor can internally allocate a dynamic array. All the input and output stream 
operators and functions can then be used to fill the array. 


You must be aware that there is a put pointer and a get pointer working inde- 
pendently behind the scenes in the attached strstreambuf class. The put pointer 
advances as you insert fields into the stream’s array, and the get pointer advances 
as you extract fields. The ostream::seekp function moves the put pointer, and the 
istream::seekg function moves the get pointer. If either pointer reaches the end of 
the string (and sets the ios::eof flag), then you must call clear before seeking. 


#include <strstrea.h> 


strstreambuf, streambuf, istrstream, ostrstream 


Construction/Destruction 


strstream Constructs a strstream object. 

~strstream Destroys a strstream object. 

Other Functions 

pcount Returns the number of bytes that have been stored 
in the stream’s buffer. 

rdbuf Returns a pointer to the stream’s associated 
strstreambuf object. 

str Returns a pointer to the string stream’s character 


buffer and freezes it. 


940 


strstream::pcount 


‘Member Functions 


Syntax 


Remarks 


Syntax 


Remarks 


See Also 


Syntax 


Remarks 


See Also 


sirstream::pcount 


int pcount() const; 


Returns the number of bytes that have been stored in the buffer. This information 
is especially useful when you have stored binary data in the object. 


sirstream::rdbuf 


strstreambuf* rdbuf() const; 


Returns a pointer to the strstreambuf buffer object that is associated with this 
stream. Note that this is not the character buffer; the strstreambuf object contains 
a pointer to the character area. 


strstream::str 


Sirstream::str 


char* str(); 


Returns a pointer to the internal character array. If the stream was built with the 
void-argument constructor, then str freezes the array. You must not send charac- 
ters to a frozen stream, and you are responsible for deleting the array. You can un- 
freeze the the stream by calling rdbuf->freeze( 0 ). 


If the stream was built with the constructor that specified the buffer, then the 
pointer contains the same address as the array used to construct the ostrstream 
object. 


strstreambuf::freeze, strstream::rdbuf 


Syntax 


Parameters 


Remarks 


Strstream::strstream 941 


sirstream::sirstream 


strstream(); 


strstream( char* pch, int nLength, int nMode ); 


pch 
A character array that is large enough to accommodate future output stream 
activity. 

nLength 
The size (in characters) of pch. If 0, then pch is assumed to point to a null- 
terminated array; if less than 0, then the array is assumed to have infinite length. 


nM ode 
The stream creation mode. Must be one of the following enumerators as de- 
fined in class ios: 


Value Meaning 

ios: :in Retrieval begins at the beginning of the array. 

ios::out By default, storing begins at pch. 

ios::ate The pch parameter is assumed to be a null-terminated array; 


storing begins at the NULL character. 


i0s::app Same as ios::ate. 


The use of the ios::in and ios::out flags is optional for this class; both input and 
output are implied. 


The first constructor makes an strstream object that uses an internal, dynamic 
buffer that is initially empty. 


The second constructor makes an strstream object out of the first nLength charac- 
ters of the psc buffer. The stream will not accept characters once the length 
reaches nLength. 
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sirstream::~sirstream 


Syntax ~strstream(); 


Remarks Destroys a strstream object and its associated strstreambuf object, thus releasing 
all internally allocated memory. If you used the void-argument constructor, then 
the internally allocated character buffer is released; otherwise, you must release it 
yourself. 


An internally allocated character buffer will not be released if it was previously 
frozen by calling rdbuf->freeze( 0 ). 


See Also strstream::rdbuf 


strstreambuf 943 


Class strstreambuf : public streambuf 


See Also 


Public Members 


The strstreambuf class is a derived class of streambuf that manages an in- 
memory character array. 


The file stream classes, ostrstream, istrstream, and strstream, use strstreambuf 
member functions to fetch and store characters. Some of these member functions 
are virtual functions defined for the streambuf class. 


The reserve area, put area, and get area were introduced in the streambuf class de- 
scription. For strsteambuf objects, the put area is the same as the get area, but the 
get pointer and the put pointer move independently. 


#include <strstrea.h> 


istrstream, ostrstream, filebuf, stdiobuf 


Construction/Destruction 


strstreambuf Constructs a strstreambuf object. 
~strstreambuf Destroys a strstreambuf object. 
Other Functions 

freeze Freezes a stream. 


str Returns a pointer to the string. 
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Member Functions 


strstreambuf::freeze 


Syntax void freeze( int n = 1 ); 


Parameters n 
A 0 value permits automatic deletion of the current array and also its automatic 
growth (if it is dynamic); a nonzero value prevents deletion. 


Remarks If a strstreambuf object has a dynamic array, then memory is usually deleted on 
destruction and size adjustment. The freeze function provides a means of prevent- 
ing that automatic deletion. Once an array is frozen, no further input or output is 
permitted. The results of such operations are undefined. 


The freeze function can also unfreeze a frozen buffer. 


See Also strstreambuf::str 


Strstreambuf::str 


Syntax char* str(); 


Remarks Returns a pointer to the object’s internal character array. If the strstreambuf 
object was constructed with a user-supplied buffer, then that buffer address is 
returned. If the object has a dynamic array, then str freezes the array. You must 
not send characters to a frozen strstreambuf object, and you are responsible for 
deleting the array. If a dynamic array is empty, then str returns NULL. 


You can use the freeze function with a 0 parameter to unfreeze a frozen 
strstreambuf object. 


See Also strstreambuf:: freeze 


strstreambuf::strstreambuf 945 


strstreambuf::strstreambuf 


Syntax strstreambuf(); 
strstreambuf( int nBytes ); 


strstreambuf( char* pch, int n, char* pstart = 0); 
strstreambuf( unsigned char* puch, int n, unsigned char* pustart = 0 ); 


strstreambuf( signed char* psch, int n, signed char* psstart = 0 ); 


strstreambuf( void* (*falloc)(long), void (*ffree)(void*) ); 


Parameters nBytes 
The initial length of a dynamic stream buffer. 


pch, puch, psch 
A pointer to a character buffer that will be attached to the object. The get 
pointer is initialized to this value. 


An integer parameter with the following meanings: 


Value Meaning 

positive n bytes, starting at pch, is used as a fixed-length stream buffer. 

0 The pch parameter points to the start of a null-terminated 
string that constitutes the stream buffer (terminator excluded). 

negative The pch parameter points to a stream buffer that continues 
indefinitely. 


pstart, pustart, psstart 
The initial value of the put pointer. 


falloc 
A memory-allocation function with the prototype void* falloc( long ). The 
default is new. 


ffree 


A function that frees allocated memory with the prototype void ffree( void* ). 
The default is delete. 
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Remarks The four streambuf constructors are described as follows: 
Constructor Description 
strstreambuf() Constructs an empty strstreambuf object with 


dynamic buffering. The buffer is allocated internally 
by the class and grows as needed, unless it is frozen. 


strstreambuf( int ) Constructs an empty strstreambuf object with a 
dynamic buffer 1 bytes long to start with. The buffer 
is allocated internally by the class and grows as 
needed, unless it 1s frozen. 


strstreambuf( char*, Constructs a strstreambuf object from already- 

int, char* ) allocated memory as specified by the arguments. 
There are constructor variations for both unsigned 
and signed character arrays. 


strstreambuf( Constructs an empty strstreambuf object with 

void*(*), void(*) ) dynamic buffering. The falloc function is called for 
allocation. The long parameter specifies the buffer 
length and the function returns the buffer address. If 
the falloc pointer is NULL, then operator new is 
used. The ffree function frees memory allocated by 
falloc. If the ffree pointer is NULL, the operator 
delete is used. 


strstreambuf::~strstreambuf 


Syntax ~strstreambuf(); 


Remarks Destroys a strstreambuf object and, in the process, releases all internally allo- 
cated dynamic memory unless the object is frozen. The destructor does not release 
user-allocated memory. 
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!= (inequality operator) [] (subscript operator) 
CRect class, 532 CMapStringToOb class, 386 
& (intersection operator) CString class, 597 
CRect class, 535 | (union operator) 
&= (assignment of intersection operator) CRect class, 535 
CRect class, 533 I= (assignment of union operator) 
+ (addition operator) CRect class, 533-534 
CRect class, 534 — (subtraction operator) 
CString class, 594 CRect class, 534 
CTime class, 615-616 CTimeSpan class, 625 
CTimeSpan class, 625 — = (assignment of subtraction operator) 
+= (assignment of addition operator) CRect class, 533 
CRect class, 532 
CString class, 595 A 
CTime class, 616 
CTimeSpan class, 626 AbortDoc member function 
16-bit words CDC class, 164-165 
CWordArray class described, 823 Aborting | 
32-bit CDC::AbortDoc, 164 
double words, CDWordArray class described, 280 default termination function, AfxAbort, 61 
values, retrieving combo-box item, print job installing procedure, 235-237 
CComboBox::GetItemData, 150 Accelerator key translation, 638 
= (assignment operator) Add member function 
CRect class, 531 CObArray class, 453 
CSize class, 560 AddHead member function 
CString class, 592 CObList class, 480 
CTime class, 615 Adding 
CTimeSpan class, 625 CWnd to Clipboard viewer chain, 807 
istream class, 889 element to array, 453 
ostream class, 910 elements to lists, 481 
= = (equality operator) filenames 
CRect class, 531 to list box of combo box, 147 
<< (insertion operator) to list boxes, 360 
CArchive class, 103 lists or elements to lists, 480 
CDumpContext class, 278-279 menu items, 428-430 
CString class, 593 size to CSize, 560 
ostream class, 906 strings 
>> (extraction operator) to list box of combo box, 142, 151 
CArchive class, 102 to list boxes, 355, 366 
CString class, 593 time spans 
CTime class, 617 CTimeSpan::operator +,—, 625 
CTimeSpan class, 627 CTimeSpan::operator +=,—=, 626 


istream class, 885 
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Addition operator 
CRect class, 534 
CString class, 594 
CTime class, 615-616 
CTimeSpan class, 625 
AddString member function 
CComboBox class, 142 
CListBox class, 355 
AddTail member function 
CObList class, 481 
adjustfield data member 
i0s class, 867 
AfxAbort, 61 
AfxCheckMemory, 47 
AfxDoForAllClasses, 48 
AfxDoForAllObjects, 49 
AfxEnableMemoryTracking, 49 
AfxGetApp, 36 
AfxGetAppName, 36 
AfxGetInstanceHandle, 36 
AfxGetResourceHandle, 37 
AfxIsMemoryBlock, 50 
AfxIsValidAddress, 51 
afxMemDF, 46 
AfxRegisterWndClass, 37 
AfxSetAllocHook, 51 
AfxSetAllocStop, 52 
AfxSetTerminate, 61 
AfxTerminate, 62 
AfxThrowArchiveException, 63 
AfxThrowFileException, 63 
AfxThrowMemoryException, 64 
AfxThrowNotSupportedException, 64 
AfxThrowResourceException, 64 
allocate member function 
streambuf class, 922 
ALT key 
called when pressed with another key, 791-792 
called with release of key pressed 
with ALT, 792—794 
AND_CATCH macro, 65 
AnimatePalette member function 
CPalette class, 503 
ANSI 


converting characters to OEM character set, 576 


AnsiloOem member function 
CString class, 576 
Appending menu items, 416-418 
AppendMenu member function 
CMenu class, 416-418 
CWnd::GetSystemMenu, 699 


Applications 


accessing device facilities unavailable through 
GDI, 184-185 
allowing access to Control menu for copying and 
modification, 699 
called when creating CWnd object, 724—726 
creating and displaying messages, 711-714 
CWnd, 735-736 
fonts, called upon changing, 738-739 
list boxes, returning on application response, 720 
main class described, 5 
owner’ s, called when destroyed, 780-781 
redrawing or preventing redrawing of changes, 811 
returning handle to current instance 
AfxGetInstanceHandle, 36 
AfxGetResourceHandle, 37 
returning name, AfxGetAppName, 36 
sessions, ending, called to inform CWnd, 736 
specifying the action performed in response to 
message, 795—796 
specifying whether given window is visible, 710 
Windows 
accessing command-line arguments entered at 
start, 639 
cleaning up at termination, 631 
constructor, 631 
CWinApp class described, 628 
filtering messages, 638 
handle to current instance, 639 
handle to previous instance, 639 
idle-time processing, 637 
instance initializing, 632 
last message retrieved, 639 
loading cursor resource, 633 
loading predefined cursor resource, 634, 635 
loading predefined icon resource, 634, 636 
loading specified icon resource, 633 
making main window visible, 640 
name, 640 
one-time initializing, 632 
providing default message loop, 638 
storing pointer to main window object, 640 


Arc member function 


CDC class, 165-166 


Archives 


CArchive class described, 93-94 
CArchiveException class described, 104 
data 
determining if loading, 98 
determining if storing, 98 


Archives (continued) 
flushing buffer to file, 97 
getting CFile pointer, 97 
loading object or primitive type, 102 
reading 
from object data, 99 
from specified number of bytes, 99 
serialization exceptions, constructing objects, 105 
specifying cause, 106 
storing 
object or primitive type, 103 
objects, 101 
writing, specified number of bytes to, 100 
Arcs, elliptical, drawing, 165-166 
Argument passing conventions 
CString class, 599 
Arguments 
evaluating 
ASSERT macro, 53 
VERIFY macro, 57 
inserting into streams, 906 
returning variable number as printf uses them, 
TRACE macro, 56 
Arrangelconic Windows member function 
CWnd class, 659 
Arranging minimized document child windows, 406 
Array classes described, 27 
Arrays 
16-bit words, CWordArray class described, 823 
adding element to, 453 
bytes, dumping hexadecimally formatted, 276 
classes described, 27 
CObject pointers, CObArray class described, 450 
CString objects, CStringArray class described, 601 
destroying, 454 
double words, CDWordArray class described, 280 
dynamic, of bytes, CByteArray class, 135—136 
elements 
adding at end, 453 
inserting in specified index, 457 
removing elements, 458-459 
returning at specified index, 455 
returning reference to pointer, 454-455 
setting at specified index, 459-460 
setting at specified index, 460-461 
establishing size, 461 
freeing extra memory, 455 
indexes, setting elements to specified, 459-460 
internal character, returning pointer to, 914 
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Arrays (continued) 
removing pointers from, 458 
returning size of, 456 
returning upper bound, 456 
returns reference to element pointer, 454-455 
strstreambuf objects, preventing memory 
deletion, 944 
subscript operators, 462 
void pointers, CPtrArray class described, 517 
Aspect-ratio filter, retrieving setting, 192 
ASSERT macro, 53 
ASSERT_VALID macro, 53 
AssertValid member function 
CObject class, 466 
Assignment of addition operator 
CRect class, 532 
CString class, 595 
CTime class, 616 
CTimeSpan class, 626 
Assignment of intersection operator 
CRect class, 533 
Assignment of subtraction operator 
CRect class, 533 
Assignment of union operator 
CRect class, 533-534 
Assignment operator 
CRect class, 531 
CSize class, 560-561 
CString class, 592 
CTime class, 615 
CTimeSpan class, 625 
istream class, 889 
ostream class, 910 
Attach member function 
CGdiObject class, 344 
CMenu class, 419 
CWhnd class, 659 
filebuf class, 832 
fstream class, 838 
ifstream class, 846 
ofstream class, 894 
Attaching 
filebuf objects to specified open file, 832 
stream to specified open file, 838 
streams 
to already open file, 894 
to specified open file, 846 
Windows GDI object to CGdiObject, 344 


Background 
CWnd, called when needing erasing, 737—738 
mode, getting, 193 
bad member function 
10s class, 855 
base member function 
streambuf class, 922 
basefield data member 
10S Class, 867 
BeginPaint member function 
CWnd class, 660 
CPaintDC::m_ps, 500 
Binary/text mode, setting 
filebuf objects, 835 
stream’s filebuf object, 851 
streams, 868, 899 
Binding, done when, 25 
Bit patterns, creating for specified device, 218-219 
bitalloc member function 
10s class, 855 
BitBlt member function 
CDC class, 167—169 
CBitmap::CreateBitmap, 110 
CBitmap::CreateBitmapIndirect, 110 
Bitmaps 
associating with menu items, 435-436 
constructing CBitmap objects, 109 
copying 
to current device context, 167-169 
bit pattern to buffer, 113 
GDI, CBitmap class described, 107-108 
initializing 
compatible with device specified by pDC, 111 
device-dependent memory bitmap, 109-110 
discardable, 112 
having lpBitmap structure, 110 
moving, 255-257 
predefined, loading, 115-116 
resource, loading, 114 
returning pointer to CBitmap object, 113 
setting bits to specified values, 116 
stretching mode, retrieving, 204 
width, height, getting, 114 
width, specifying, 116-117 
BLACKRECT structure, 564 


blen member function 
streambuf class, 922 
Borders, drawing 
around rectangles, 191 
around regions, 192 
BottomRight member function 
CRect class, 523 
Boxes, setting highlighting, 134 
Boxes, buttons 
getting 
check state, 132 
current state, 132 
setting check state, 134 
Bring WindowToTop member function 
CWhnd class, 661 
Brushes 
available in device context, enumerating, 182-184 
CBrush class described, 118 
CBrush object, returning pointer to, 125 
constructing uninitialized, 119-120 
current, retrieving origin, 193 
initializing 
DIB-specified pattern, 121—122 
hatch pattern and color, 122—124 
LOGBRUSH-specified pattern, 120-121 
pattern specified by bitmap, 123 
solid color, 124 
predefined 
retrieving handle to, 345-346 
selecting, 442 
resetting CGdiObject::UnrealizeObject, 350 
setting origin for GDI assignment, 239 
Buffer-deletion flags, assigning value for stream, 
856 
Buffering 
setting state for streambuf object, 937 
Buffers 
archive, flushing 
CArchive::Close, 97 
CArchive::Flush, 97 
filling with data that defines object, 348 
flushing 
files, 309 
to dump context, 275 
internal character, returning pointer for CString 
object, 582-583 
streams, flushing, 902 
writing data to CFile object file, 320 


Button control 
calling owner when visual aspect of control or 
menu changes, 732-735 
check-marking, dimming, 661 
determining check-marking, 709 
Buttons 
as child windows, 16 
check-marking, 662 
creating 
constructor, 128 
control, 128-131 
styles 
changing, 33 
getting, 131 
Buttons, boxes 
called when control created, 754-756 
calling owner when visual aspect of control or 
menu changes, 732—735 
check-marked, getting ID of radio button, 686 
Bytes, dumping array of hexadecimally formatted, 
276 


dynamic array support, 135-136 
extracting from streams, 883 
file length, 309 

locking range in open file, 312 
writing to streams, 905 


C 


C++ 

accommodates Windows messaging, 9 

and Windows, 8 

constructors, 15 

Windows objects, constructing, 15 
C++ header code 

generating for CObject class 

serializable, 468 
with run-time information, 468 
generating for dynamic CObject-derived class with 
run-time access to class name and position, 471 

CALCRECT structure, 177-179 
Calculating 

height of CRect, 525 

nonclient area, 762 

width of CRect, 530 
Callback function, 183, 211, 236 
Cancel button, overriding in dialog boxes, 448 
CanUndo member function 

CEdit class, 285 
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Captions 
dialog boxes, retrieving, 691 
setting to specified text, 816 
CArchive class 
described, 93-94 
member functions 
CArchive, 95—96 
~CArchive, 96 
Close, 96—97 
Flush, 96-97, 309 
GetFile, 97 
IsLoading, 98, 473 
IsStoring, 98, 473 
Read, 99 
ReadObject, 99-100, 473 
Write, 100 
WriteObject, 101, 473 
object persistence described, 23 
operators, 102—103 
CArchive constructor, 95—96 
CArchive destructor, 96 
CArchive object 
closing and disconnecting from file, 97 
creating, 95 
destroying, 96 
CArchiveException class 
data members 
m_cause, 106 
described, 104 
member functions 
CArchiveException, 105 
CArchiveException constructor, 105 
Carets 
coordinates, retrieving, 686 
displaying 
after gaining input focus, 783 
at current position, 816—817 
gray, creating, 671 
hiding, 705 
moving to position specified by point, 806-807 
solid, creating, 672 
system, creating new shape, 665 
Casting operator, 592 
CATCH macro, 65 
CBitmap class 
described, 107-108 
member functions 
CBitmap, 109 
CreateBitmap, 109-110, 120, 123, 665 
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CBitmap class (continued) 
member functions (continued) 
CreateBitmapIndirect, 110, 120, 123 
CreateCompatibleBitmap, 111, 120, 123 
CreateDiscardableBitmap, 112 
FromHandle, 113 
GetBitmapBits, 113, 349 
GetBitmapDimension, 114 
LoadBitmap, 114, 120, 123, 665 
LoadOEMBitmap, 115-116 
SetBitmapBits, 116 
SetBitmapDimension, 116-117 
CBitmap constructor, 109 
CBrush::CBrush, 120 
CBitmap object 
copying bit pattern to buffer, 113 
creating, 109 
returning pointer, 113 
CBitmap, width, height, getting, 114 
CBrush class 
described, 118 
member functions 
CBrush, 119—120 
CreateBrushIndirect, 120-121 
CreateDIBPatternBrush, 121—122 
CreateHatchBrush, 122-123 
CreatePatternBrush, 123-124 
CreateSolidBrush, 124 
FromHandle, 125 
UnrealizeObject, 738 
CBrush constructor, 119-120 
CBrush object, creating uninitialized, 119-120 
CButton class 
described, 126—127 
member functions 
CButton, 128 
Create, 128-131 
GetButtonStyle, 131 
GetCheck, 132 
GetState, 132—133 
SetButtonStyle, 133 
SetCheck, 134 
SetState, 134 
setting highlight state, 134 
CButton constructor, 128 
CButton object 
control, 128-131 
creating, 128 
CByteArray class, described, 135-136 


CClientDC class 
data members 
m_hWnd, 138 
described, 137 
member functions 
CClientDC, 138 
~CClientDC, 138 
CClientDC constructor, 138 
CClientDC destructor, 138 
CClientDC objects 
creating, 138 
destroying, 138 
handles, 138 
CComboBox class 
described, 139-141 
edit control 
copies current selection to Clipboard, 143 
deleting selection, 143 
inserting Clipboard data into, 152 
selecting characters in, 154 
text, limiting length, 152 
items 
getting number of, 149 
retrieving associated application-supplied 32-bit 
value, 150 
setting associated with 32-bit value, 155 
list box 
adding string to, 142 
removing all items from, 153 
searching for string in, 153 
selecting string in, 154 
showing or hiding specified, 155 
member functions 
AddString, 142 
CComboBox, 142 
Clear, 143 
Copy, 143 
Create, 143-146 
Cut, 146 
DeleteString, 147, 729 
Dir, 147-148 
FindString, 148 
GetCount, 149 
GetCurSel, 149 
GetEditSel, 149 
GetItemData, 150 
GetLBText, 150 
GetLBTextLen, 151 
InsertString, 151 


CComboBox class (continued) 


member functions (continued) 
LimitText, 152 
Paste, 152 
ResetContent, 153, 729 
SelectString, 153 
SetCurSel, 154 
SetEditSel, 154-155 
SetItemData, 155 
ShowDropDown, 155 


CComboBox constructor, 142 
CComboBox object 


creating, 143-144, 146 
ending print job page, 181 
printing, terminating job, 180 


CDC class 


allowing applications to access device facilities, 
184-185 
bit pattern, creating, 218-219 
bitmaps, moving, 255, 257 
bitmap-stretching mode, retrieving, 204 
CGdiObject object, selecting, 234-235 
character strings 
computing width and height, 204—205 
writing, with tab stops, 258-259 
clipping region 
creating, 185 
selecting given region as current, 231 
colors 
retrieving current text,207 
retrieving RGB value of specified pixel, 202 
returning closest to device capability, 202 
setting background, 238 
Setting text, 248 
updating client area with current, 260 
converting logical to device points, 215 
copying bitmap, 167-169 
creating 
bit pattern on device, 218-219 
clipping region, 212 
current position, retrieving, 195 
described, 156-163 
device contexts 
creating for specified device, 172-173 
deleting, 174 
obtaining final translation origin, 196 
Saving current state, 227 
display device, getting information on, 196, 201 
drawing 
dimmed text, 210-212 
ellipses, 179-180 
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CDC class (continued) 

drawing (continued) 
elliptical arcs, 165-166 
filled polygons, 222 
icons, 176 
line segments, 222 
lines to points, 214 
pie-shaped wedge, 219-220 
polygons consisting of points, 221 
rectangles in focus style, 175 
rectangles with current pen, 224 
rectangles with rounded corners, 226—227 
setting current mode, 243-244 

drawing mode, retrieving, 203 

dynamic run-time checking supported, 156 

filling 
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display area with current brush, 187-188, 190 


rectangle using specified brush, 189-190 
specified region with brush, 218 
fonts 
altering mapper, 241 
copying typeface name into buffer, 208 
retrieving character widths, 194 
retrieving metrics for current, 208 
information contexts, creating, 173 
intercharacter spacing setting, 206 
mapping mode, retrieving, 201 
mapping point coordinates, 175 
member functions 
AbortDoc, 164—165 
Arc, 165—166 
BitBlt, 110, 167-169 


CreateCompatibleDC, 171-172 
CreateDC, 172-173 
CreateIC, 173-174 
DeleteDC, 174-175 
DPtoLP, 175 
DrawFocusRect, 175-176 
DrawlIcon, 176 

DrawText, 177-179 
Ellipse, 179-180 

EndDoc, 180-181 
EndPage, 181-182 
EnumObjects, 182-184 
Escape, 184—185 
ExcludeClipRect, 185-186 
ExcludeUpdateRgn, 186 
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CDC class (continued) CDC class (continued) 
member functions (continued) member functions (continued) 

ExtFloodFill, 187-188 Polygon, 221 
ExtTextOut, 188—189 Polyline, 222 
FillRect, 189-190 PolyPolygon, 222—223 
FillRgn, 190 PtVisible, 223 
FloodFill, 190-191 RealizePalette, 224, 350, 507 
FrameRect, 191 Rectangle, 224—225 
FrameRgn, 192 RectVisible, 225 
GetAspectRatioFilter, 192 RestoreDC, 226 
GetBkColor, 193 RoundRect, 226—227 
GetBkMode, 193 SaveDC, 227-228 
GetBrushOrg, 193-194 ScaleViewportExt, 228 
GetCharWidth, 194 ScaleWindowExt, 229 
GetClipBox, 195 ScrolIDC, 230 
GetCurrentPosition, 195 SelectClipRgn, 231 
GetDCOrg, 196 SelectObject, 110, 112, 232—233, 334 
GetDeviceCaps, 196-201 SelectPalette, 233—234 
GetMapMode, 201 SelectStockObject, 234—235 
GetNearestColor, 202 SetAbortProc, 235-237 
GetPixel, 202~203 SetBkColor, 238 
GetPolyFillMode, 203 SetBkMode, 238-239 
GetROP2, 203 SetBrushOrg, 239, 350 
GetStretchBltMode, 204 SetMapMode, 240-241 
GetTabbedTextExtent, 204—205 SetMapperFlags, 241 
GetTextAlign, 205—206 SetPixel, 242 
GetTextCharacterExtra, 206 | SetPolyFillMode, 242-243 
GetTextColor, 207 SetROP2, 243-244 
GetTextExtent, 207 SetStretchBltMode, 245 
GetTextFace, 208 SetTextAlign, 246-247 
GetTextMetrics, 208 SetTextCharacterExtra, 247 
GetViewportExt, 209 SetTextColor, 248 
GetViewportOrg, 209 SetTextJustification, 248—249 
Get WindowExt, 209 Set ViewportExt, 250 
GetWindowOrg, 210 SetViewportOrg, 251 
GrayString, 210-212 SetWindowExt, 252 
IntersectClipRect, 212—213 SetWindowOrg, 253 
InvertRect, 213 StartDoc, 254 
InvertRgn, 214 StartPage, 254 
LineTo, 214 StretchBlt, 255—257 
LPtoDP, 215 TabbedTextOut, 258-259 
MoveTo, 215—216 TextOut, 259-260 
OffsetClipRgn, 216 UpdateColors, 260 
Offset ViewportOrg, 217 metafile, playing on device, 221 
OffsetWindowOrg, 217 modifying 
PaintRgn, 218 viewport extents, 228 
PatBlt, 218-219 window origin, 217 
Pie, 219—220 windows extents, 229 


PlayMetaFile, 221, 440 


CDC class (continued) 
moving clipping region, 216 
mapping entries to system palette, 224 
selecting, 233 
pens, brushes available, enumerating, 182—184 
pixels, setting at specified point, 242 
polygon-filling mode 
retrieving, 203 
setting, 242 
position, current, moving to point, 215 
print job, informing device driver of new, 254 
printer driver, preparing to receive data, 254 
printing 
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CDC class (continued) 
text 
computing line dimensions, 207 
setting alignment flags, 246-247 
setting color, 248 
setting justification, 248—249 
text-alignment flag status, retrieving, 205 
viewports 
modifying origin, 217 
retrieving device contexts’ extents, 209 


retrieving origin coordinates associated with 


device context, 209 
setting origins of device context, 251 
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installing abort procedure for job, 235-237 


setting x- and y-extents of device context, 250 


terminating current job, 164 


rectangles 


bounding, retrieving dimensions around clipping 
195 
determining if within clipping region, 225 


windows, 253 
retrieving coordinates associated with device 
context, 209 
setting x- and y-extents, 252 
writing character strings at specified location, 259 


drawing borders around, 191 
drawing text in, 177-179 
drawing with rounded corners, 226-227 
inverting contexts, 213 
scrolling, 230 
regions 
drawing border around, 192 
filling with specified brush, 190, 218 
inverting contents, 214 


preventing drawing within invalid area, 186 


writing character strings within, 188-189 
restoring Windows device context to previous 
state, 226 
retrieving 
aspect-ratio filter setting, 192 
current brush origin, 193 
window origin coordinates, 210 
returning 
background mode, 193 
current background color, 193 
selecting object into current device context, 
232-233 
setting 
background mode, 238 
bitmap-stretching mode, 245 
current drawing mode, 243-244 
intercharacter spacing, 247 
mapping mode, 240-241 
specifying next brush origin, 239 
terminating print job 
CDC::AbortDoc, 164 
CDC::EndDoc, 180 


CDC constructor, 169 
CDC destructor, 170 
CDC objects 


creating and attaching memory device context, 171 


constructor, 169 
destroying, 170 
CDialog class 

described, 261-263 

focus control 
CDialog::GotoDlgCtrl, 268 
CDialog::NextDlgCtrl, 270 
previous, 272 

font control, 262 
CDialog::OnSetFont, 271 

member functions 
CDialog, 264 
Create, 264—265 
CreateIndirect, 266—267 
EndDialog, 267 
GetDefID, 268 
GotoDlgCtrl, 268 
IsDialogMessage, 268-269 
MapDialogRect, 270 
NextDlgCtrl, 270 
OnInitDialog, 271 
OnSetFont, 271-272 
PrevDlgCtrl, 272 
SetDefID, 272 

message-checking, 268—269 

message-handler member functions, 261 

modeless dialog box, creating, 264 

pushbutton control, default, 272 
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CDialog class (continued) 
screen unit conversion control, 270 
standard dialog box procedure, 271 


standard Foundation dialog box procedure, 267 


CDialog constructor, 264 
CDumpContext class 
described, 273-274 
member functions. 
CDumpContext, 275 
Flush, 275 
GetDepth, 276 
HexDump, 276 
SetDepth, 277 
operators, 278-279 
CDumpContext constructor, 275 
CDumpContext objects, creating, 275 
CDWordArray class 
described, 280-281 
CEdit class 
described, 282—284 
member functions 
CanUndo, 285 
CEdit, 285 
Clear, 285 
Copy, 286 
Create, 286-289 
Cut, 289 
EmptyUndoBuffer, 290 
FmtLines, 290 
GetHandle, 291 
GetLine, 291—292 
GetLineCount, 292 
GetModify, 292-293 
GetRect, 293 
GetSel, 293 
LimitText, 294 
LineFromChar, 294 
LineIndex, 295 
LineLength, 295-296 
LineScroll, 296 
Paste, 297 
ReplaceSel, 297 
SetHandle, 297-298 
SetModify, 298 
SetPasswordChar, 299 
SetRect, 299-300 
SetRectNP, 300 
SetSel, 301 
SetTabStops, 301-302 
Undo, 302 


CEdit constructor, 285 
CEdit object 
creating 
attaching, 286-289 
constructor, 285 
cerr, predefined stream object, 900 
CException class 
described, 303 
CFile class 
data members 
m_hFile, 321 
described, 304—305 
family described, 26 
member functions 
CFile, 306-308 
~CFile, 308 
Close, 97, 308 
Duplicate, 309 
Flush, 309 
GetLength, 309 
GetPosition, 96, 310 
GetStatus, 310-312 
LockRange, 312-313 
Open, 313-314, 568 
Read, 314, 570 
Remove, 315 
Rename, 315-316 
Seek, 316-317 
SeekToBegin, 317 
SeekToEnd, 317 
SetLength, 318 
SetStatus, 318-319 
UnlockRange, 319 
Write, 320, 570 
CFile constructor, 306—308 
CArchive::CArchive, 96 
CStdioFile::CStdioFile, 568 
CFile destructor, 308 
CFile objects 
closing associated file, 308 
creating 
constructor, 306 
safe method, 313 
destroying, 308 
duplicating, 309 
reading data into buffer, 314 
retrieving file status, 310-311 


CFileException class 
data members 
m_cause, 327-328 
m_lOsError, 328 
described, 322-323 
enumerators, 327 
member functions 
CFileException, 324 
ErmoToException, 324—325 
OsErrorToException, 325 
ThrowErrno, 325-326 
ThrowOsEtrror, 326 
operating system error codes, 325 
CFileException object 
creating 
and throwing exception, 
constructor, 324 
CFont class 
described, 329 
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CFrameWnd object 


creating 
attaching, 338-339 
constructor, 338 
destroying, 338 


CGdiObject class 


data members 
m_hObject, 351 

described, 342-343 

member functions 
Attach, 344 
CGdiObject, 344 
~CGdiObject, 345 
CreateStockObject, 345-346 
DeleteObject, 272, 346-347 
DeleteTempMap, 347 
Detach, 347 
FromHandle, 348 
GetObject, 348-349 


member functions GetSafeHandle, 349 
CFont, 330 UnrealizeObject, 350 
CreateFont, 330-333 resetting brush origin or logical palette, 350 
CreateFontIndirect, 334 CGdiObject constructor, 344 
FromHandle, 335 CGdiObject destructor, 345 
described, 329 CGdiObject objects 
CFont objects brushes, resetting, 350 


creating, 330 
handle to, 335 
initializing 


LOGFONT-specified characteristics, 334 
specified characteristics, 330-333 


CFrameWnd 
accelerator table, loading, 340 
overridable member function, 340 
CFrameWnd class 
data members 
m_hAccelTable, 341 
rectDefault, 341 
described, 336—337 
member functions 
CFrameWnd, 338 
~CFrameWnd, 338 
Create, 338-339 
GetChildFrame, 339 
GetParentFrame, 340 
LoadAccelTable, 340 
CFrameWnd constructor, 338 
CFrameWnd destructor, 338 


creating, 344 
deleting 
objects, 346 
temporary, 347 
destroying, 345 
detaching Windows GDI object from, 347 
filling buffer with data definition, 348 
handles, 351 
palettes, resetting, 350 
retrieving handle to, 345-346 
returning handle to, 349 
returning pointer with GDI object handle, 348 
selecting, 232-235 


ChangeClipboardChain member function 


CWnd class, 661 
CWnd object position and dimensions, changing, 
714-715 
fonts called when, 738-739 
menu items, 432-433 
position 
relative to stream beginning, 930 
streambuf objects, 929 
stream’s, 904 
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Chaining 
file length, 318 
Character sets 
ANSI, converting to OEM, 576 
OEM, converting to ANSI, 588 
Character arrays 
returning pointer to string stream’s, 892 
Characters 
dead-key, returning value, 727—729 
edit control, getting starting, ending character 
positions, 293 
extracting 
from stream and discarding, 880 
putting back into stream, 882 
fill, setting for stream, setfill, 869 
index 
of line, retrieving within multiple-line edit 
control, 295 
retrieving line number from multiple-line edit 
control, 294 
inserting into output stream, 903 
mnemonic, called when user presses, 756-757 
newline, inserting into output streams, 907 
null-terminator, inserting into output streams, 907 
number of positions to scroll horizonally, 296 
passwords, setting or removing in edit control, 299 
retrieving current font width, 194 
returning count of characters in CString object, 584 
returning without extracting, 882 
searching for first match in string, 581 
selecting 
combo box edit control, 154 
setting 
intercharacter spacing, 247 
range in edit control, 301 
retrieving intercharacter spacing, 206 
soft line-break, inserting in multiple-line edit, 290 
streams, returning number extracted by last 
unformatted input function, 877 
strings 
computing width, height, 204—205 
returning character specified by index, 581 
writing 
strings to regions, 188-189 
strings to specified location, 
CDC::TabbedTextOut, 258-259 
CDC::TextOut, 259 
Check boxes 
getting check state, 132 
setting check state, 134 


Check marks, adding or removing in pop-up menu, 
419-420 
CheckDlgButton member function 
CWnd class, 661-662 
Checking 
equality between sizes, 560 
inequality between sizes, 560 
Check-mark control, CWnd button control, 709 
Check-marking, button control, 661 
CheckMenulItem member function 
CMenu class, 419-420 
CheckRadioButton member function 
CWhnd class, 662 
Child windows 
activating next child, 407 
buttons as, 16 
called on activation or deactivation, 753—754 
called on creation or destruction, 774—775 
called when about to be drawn, 726—727 
called when changing size or position, 720 
changing 
parent, 810 
size, position, ordering, 814-816 
classes (list), 6 
CMDIChildWnd class described, 395 
creating 
and attaching, 397 
constructor, 397 
determining which contains specified point, 
662-663 
flashing once, 683-684 
handling activation message, 398 
identifying, 709 
MDI 
activating, 405 
arranging in cascade, 406 
arranging in tiled format, 409 
destroying, 399 
maximizing, 399, 407 
restoring, 399, 408 
returning active child, 405 
returning current, 406 
minimized, arranging, 659 
returning parent MDI frame, 398 
top-level, searching for, 700 
Windows, creating 
attaching to CWnd object, 664—665 
constructor, 673 | 
ChildWindowFromPoint member function 
CWnd class, 662—663 


Chord member function 
CDC class, 170-171 
Chords, drawing, 170-171 
cin, predefined stream object, 875 
Classes 
derivation, 10 
general purpose, categorized by function (list), 21 
run-time information, supplying, 38—39 
Windows 
described, 5 
registering, 37 
Clear member function 
CComboBox class, 143 
CEdit class, 285 
clear member function 
10S class, 856 
Clearing 
edit control 
selection, 285 
undo flag, 290 
error-bits, 856 
format flags 
10s::unsetf, 864 
streams, 869 
Client areas 
called after size changed, 784-785 
called when needing repainting, 772-773 
called when size changed and Clipboard contains 
data, 785 
calling windows, CClientDC class, 137 
CClientDC class described, 137 
converting screen coordinates of point or rect to 
client coordinates, 802 
CWnd, copying client coordinates into specified 
structure, 686-687 
device contexts 
creating, 138 
destroying, 138 
invalidating 
CWnd::Invalidate, 706 
entire, 707 
within given rectangle, 707 
within given region, 708 
painting 
information, 84—85 
window associated with CPaintDC object, S00 
scrolling, 803-804 
updating 
CWnd::UpdateWindows, 819 
matching colors, 260 
validating within given region, 820 
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Client coordinates, converting to screen 
coordinates, 663 
CLIENTCREATESTRUCT structure 
CMD IFrameWnd::CreateClient, 404 
ClientToScreen member function 
CWnd class, 663 
Clipboard 
called for each window in viewer 
chain when contents change, 731—732 
calling owner when emptied, 731 
combo box edit control 
copying current selection to, 143 
copying deleted selection to, 146 
inserting data, 152 
copying edit control selection to, 286 
CWnd, called with event in vertical scroll bar, 
797-198 
format, specifying, 781 
formats (list), 86-87 
opening, 799 
owner 
called when application is destroyed, 780-78 1 
retrieving, 687 
Clipboard viewers 
called for displaying Clipboard contents, 716—717 
called for each window in chain when Clipboard 
contents change, 731—732 
called when client area needs repainting, 772-773 
called when client area size changed, 785 
chain 
adding current CWnd to, 807 
retrieving first window in, 687 
horizontal scrolling, 742-743 
removing CWnd from chain, 661 
removing windows from chain, 717-718 
Clipping region 
creating 
CDC::IntersectClipRect, 212 
CDC::ExcludeClipRect, 185 
device contexts, specifing whether point is within, 
223 
moving, 216 
rectangles, determining if within, 225 
selecting given region as current, 231 
smallest bounding rectangle dimensions, 195 
CList boxes 
setting 
tab-stop positions, 371 
CListBox class 
adding strings, 355 
bounding rectangle, retrieving dimensions, 363 
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CListBox class (continued) 
described, 352-354 
getting string length, 366 
items 

deleting, 359 
ensuring visibility, 372 
removing, 367 


retrieves zero-based index of currently selected, 


362 
retrieving index of first visible, 366 
retrieving index of, 363 
retrieving number of, 361 
retrieving selection state, 364 
retrieving total selected, 364 
searching for matching, 367 
selecting consecutive, , 368 
setting associated 32-bit values, 370 
member functions 
AddString, 355 
CListBox, 355 
Create, 356-359 
DeleteString, 359, 729 
Dir, 360 
FindString, 361 
GetCount, 361 
GetCurSel, 362 
GetHorizontalExtent, 362 
GetItemData, 363 
GetItemRect, 363 
GetSel, 364 
GetSelCount, 364 
GetSelltems, 364—365 
GetText, 365 
GetTextLen, 366 
GetTopIndex, 366 
InsertString, 366-367 
ResetContent, 367, 729 
SelectString, 367-368 
SelltemRange, 368 
SetColumn Width, 369 
SetCurSel, 369 
SetHorizontalExtent, 370 
SetItemData, 370 
SetSel, 371 
SetTabStops, 371-372 
SetTopIndex, 372 
multicolumn list box, selecting width, 369 
retrieving horizontal scroll event, 362 


CListBox class (continued) 
scrolling 
selected strings, 369 
setting width, 370 
selecting strings in multiple-selection, 371 
CListBox constructor, 355 
CListBox objects, creating 
constructor, 355 
specifying style, 356—359 
clog, predefined stream object, 900 
Close member function 
CArchive class, 96—97 
CFile class, 308 
CArchive::Flush, 97 
CMetaFileDC class, 440 
close member function 
filebuf class, 832 
fstream class, 838 
ifstream class, 846 
ofstream class, 894 
CloseWindow member function 
CWhnd class, 664 
Closing 
file associated with filebuf object, 838 
files 
associated with filebuf object, 894 
attached to filebuf object, 832 
CFile object, 308 
filebuf objects, 846 
memory, 412 
operating system file, 308 
CMapPtrToPtr class 
described, 373-374 
CMapPtrToWord class 
described, 375-376 
CMapStringToOb class 
described, 377-378 
member functions 
CMapStringToOb, 379 
~CMapStringToOb, 379 
GetCount, 380 
GetNextAssoc, 380-381 
GetStartPosition, 381 
IsEmpty, 382 
Lookup, 382 
RemoveAll, 383 
RemoveKey, 383-384 
SetAt, 384-385 
operators, 386 


CMapStringToOb constructor, 379 
CMapStringToOb destructor, 379 
CMapStringToOb objects 
constructing, 379 
destroying, 379 
CMapStringToPtr class 
described, 387—388 
CMapStringToString class 
described, 389-390 
CMapWordToOb class 
described, 391—392 
CMapWordToPtr class 
described, 393-394 
CMDIChildWnd class 
data members 
m_pMDIFrameWnd, 400 
described, 395-396 
member functions 
CMDIChildWnd, 397 
Create, 397-398 
GetParentFrame, 398 
MDtIActivate, 398 
MD Destroy, 399 
MDIMaximize, 399 
MD IRestore, 399 
CMDIChildWnd constructor, 397 
CMDIFrameWnd class 
data members 
m_hWndMD!IClient, 410 
described, 401—402 
member functions 
CMDIFrameWnd, 403 
Create, 403-404 
CreateClient, 404 
GetChildFrame, 405 
MDIActivate, 405, 754 
MDICascade, 406 
MbD1[GetActive, 406 
MDI conArrange, 406, 659 
MDIMaximize, 407 
MDINext, 407 
MDyIRestore, 408 
MDISetMenu, 408—409 
MDITile, 409 
CMDIFrameWnd constructor, 403 
CMDIFrameWnd objects 
creating 


CMDIFrameWnd::CMDIFrameWnd, 403 
Windows MDI frame window for, creating, 403 
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CMemFile class 
described, 411 
member functions 
CMemFile, 412 
~CMemFile, 412 
CMemFile constructor, 412 
CMemFile destructor, 412 
CMemoryException class 
described, 413 
member functions 
CMemoryException, 413 
CMemoryException constructor, 413 
CMemoryException objects, creating, 413 
CMemoryState objects 
comparing two, 55 
creating, 54 
CMemoryState::DumpAllObjectsSince, 54 
CMemoryState::DumpStatistics, 54 
CMenu class 
described, 19, 414415 
member functions 
AppendMenu, 416-418, 699 
Attach, 419 
CheckMenultem, 419-420 
CMenu, 420 
~CMenu, 421 
CreateMenu, 421 
CreatePopupMenu, 421-422 
DeleteMenu, 422 
DestroyMenu, 423, 810 
Detach, 423 
EnableMenultem, 423-424 
GetMenultemCount, 424 
GetMenultemID, 425 
GetMenuState, 425-426 
GetMenuString, 427 
GetSubMenu, 428 
InsertMenu, 428—430, 699 
LoadMenu, 430 
LoadMenulndirect, 431 
ModifyMenu, 432-433, 699 
RemoveMenu, 434 
SetMenultemBitmaps, 435-436 
TrackPopupMenu, 436-437 
CMenu constructor, 420 
CMenu destructor, 421 
CMenu object 
creating, 420 
destroying menus, 423 
detaching menus, 423 
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CMenu object (continued) 
loading, 430 
retrieving from pop-up, 428 
CMetaFileDC class 
described, 438—439 
member functions 
Close, 440 
CMetaFileDC, 440 
Create, 441 
SelectObject, 110, 112, 334, 441-442 
SelectStockObject, 442 
CMetaFileDC constructor, 440 
CMetaFileDC object 
creating 
constructor, 440 
device context,441 
CModalDialog class 
Cancel button action, overriding, 448 
described, 443-444 
invoking dialog box and returning result, 447 
member functions 
CModalDialog, 446 
CreateIndirect, 446-447 
DoModal, 447 
OnCancel, 448 
OnOK, 448 
OK button, overriding in dialog boxes, 448 
CModalDialog constructor, 446 
CModalDialog objects 
creating 
constructor, 446 
indirectly, 446-447 
CNotSupportedException class 
described, 449 
member functions 
CNotSupportedException, 449 
CNotSupportedException object, creating, 449 
CObArray class 
described, 450-452 
member functions 
Add, 453 
CObArray, 454 
~CObArray, 454 
ElementAt, 454-455 
FreeExtra, 455 
GetAt, 455 
GetSize, 456 
GetUpperBound, 456 
InsertAt, 456-457 
operator , 462 
RemoveAll, 458 


CObArray class (continued) 
member functions (continued) 
RemoveAt, 458-459 
SetAt, 459-460 
SetAtGrow, 460-461 
SetSize, 461 
CObArray constructor, 454 
CObAtrray destructor, 454 
CObject 
validity checking, 466 
CObject class 
described, 463—465 
executing specified iteration function for derived 
objects, 49 
getting run-time structure, 470 
giving serialization capability, 39-40 
member functions 
AssertValid, 466 
CObject, 467 
~CObject, 467 
Dump, 279, 469-470 
GetRuntimeClass, 470-471 
IsKindOf, 100, 472 
IsSerializable, 473 
Serialize, 473 
object diagnostics, 24 
operators, 475-476 
performing optimal memory allocation, 475 
persistence described, 23 
run-time class information, 25 
services provided, 23-26 
validity checking, 25 
CObject constructor, 467 
CObject destructor, 467 
CObject objects 
creating, 467 
destroying, 467 
dumping to, 469-470 
reading or writing to archive, 473-474 
testing 
for class, 472 
if eligible for serialization, 473 
CObject pointer lists 
adding element after specified position, 491-492 
adding element before specified position, 492 
creating, 482-483 
destroying, 483 
getting number of elements in, 485 
getting pointer representing head element, 486—487 
getting position of head element, 487 
getting position of next element, 488 


CObyject pointer lists (continued) 


getting position of previous element, 489 
getting tail element position, 491 

getting tail element, 490 

indicating if containing no elements, 493 
removing all elements from, 493 
removing head element from, 495 
removing specified element from, 494 
removing tail element from, 496 
retrieving pointer to given position, 485 
searching for first matching pointer, 483 
writing pointer to specified position, 496 


CObject pointers 


arrays 
adding element to end of, 453 
constructing empty, 454 
destroying, 454 

CObArray class described, 450 

lists. See Lists 


CObList class 


described, 477-479 

member functions 
AddHead, 480 
AddTail, 481 
CObList, 379, 466, 482-483 
~CObList, 483 
Find, 483-484 
FindIndex, 484 
GetAt, 485 
GetCount, 485-486 
GetHead, 486-487 
GetHeadPosition, 487 
GetNext, 488-489 
GetPrev, 489—490 
GetTail, 490 
GetTailPosition, 491 
InsertAfter, 491—492 
InsertBefore, 492-493 
IsEmpty, 493 
RemoveAll, 493-494 
RemoveAt, 494-495 
RemoveHead, 495 
RemoveTail, 496 
SetAt, 496-497 
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Collection classes 


array classes described, 27 

described, 26—27 

list classes described, 27 

maps classes described, 27 

storing objects of CObject-derived classes, 26 


Colors 


background 
returning current for device context, 193 
setting, 238 
brushes, creating, 124 
called when child-system control class about to be 
drawn, 726-727 
inverting in specified region, 214 
matching current to update client area, 260 
palettes, setting RGB values and flags in logical 
palette, 506 
retrieving, RGB value of specified pixels, 202 
returning, closest to specified logical color, 202 
system setting, called when change made, 788 
text 
retrieving current, 207 
setting, 248 


CombineRgn member function 


CRen class, 539-540 


Combo boxes 


called when control created, 754, 756 
CComboBox class described, 139-140 
comparing items in, 722, 724 
control, calling owner when visual aspect or menu 
changes, 732-735 
control, filling with directory listing, 678-679 
creating 
attaching, 143-146 
constructor, 142 
describing deleted item, 80 
destroying, 729-730 
edit control 
deleting selection and copying to Clipboard, 146 
deleting selection, 143 
getting position of current selection, 149 
inserting Clipboard data into, 152 
limiting text length, 152 
selecting characters in, 154 


CObList constructor, 482—483 items 


CMapStringToOb::CMapStringToOb, 379 
CObject::AssertValid, 466 


retrieving associated application-supplied 32-bit 
value, 150 


CObList destructor, 483 setting associated with 32-bit value, 155 
Collate member function list boxes 
CString class, 576-577 adding list of filenames to, 147 
adding string to, 142 
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Combo boxes (continued) 
list boxes (continued) 
deleting string in, 147 


finds first string containing specified prefix, 148 


getting string from, 150 
inserting string into, 151 
items in, getting number, 149 
returning selected items, 149 
searching for string in, 153 
selecting string in, 154 
showing or hiding specified, 155 
listing all items from, 153 
retrieving current selection from list box, 680-681 
supplying identifiers for two items in, 77—78 
Compare member function 
CString class, 577 
COMPAREITEMSTRUCT structure, 77—78 
CWnd::OnCompareltem, 722-723 
CompareNoCase member function 
CString class, 577-578 
Comparing 
absolute time, 616 
CMemoryState objects, 55 
items in combo boxes, 722, 724 
strings 
CString::Collate, 576 
CString::Compare, 577 
CString::CompareNoCase, 577-578 
time, two relative values, CTimeSpan comparison 
operators, 626 
Comparison operators 
CString class, 596 
Compatibility, with special collection classes, 26 
Computing 
string’s width, height, 204—205 
text’s line width, height, 207 
Concatenation operator 
CString::operator +, 594 
CString: :operator +=, 595 
const char *() operator 
CString class, 592-593 
Construction of objects, two-phase, 15 
Constructors 
CArchive, 95—96 
CArchiveException, 105 
CBitmap, 109 
CBrush, 119-120 
CButton, 128 
CClientDC, 138 
CComboBox, 142 
CDC, 169 
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CDialog, 264 
CDumpContext, 275 
CEdit, 285 

CFile, 306—308 
CFileException, 324 
CFont, 330 
CFrameWnd, 338 
CGdiObject, 344 
CListBox, 355 
CMapStringToOb, 379 
CMDIChildWnd, 397 
CMDIFrameWnd, 403 
CMemfFile, 412 
CMemoryException, 413 
CMenu, 420 
CMetaFileDC, 440 
CModalDialog, 446 
CObaArray, 454 
CObject, 467 

CObList, 482-483 
CPaintDC, 499 
CPalette, 503 

CPen, 509-510 
CPoint, 513 

CRect, 524 
CResourceException, 536 
CRegn, 545 

CScrollBar, 553 
CSize, 559 

CStatic, 563 
CStdioFile, 568-569 
CString, 578-579 
CTime, 608-609 
CTimeSpan, 620-621 
CWinApp, 631 

CWnd, 673 

filebuf, 833 

fstream, 839-841 
ifstream, 847—848 

108, 860 

10stream, 873 
Iostream_init, 874 
istream, 881 
istream_withassign, 888 
istrstream, 891 
ofstream, 895-897 
ostream, 903 
ostream_withassign, 909 
ostrstream, 912 
stdiobuf, 916 


Constructors (continued) 
stdiostream, 918 
streambuf, 936 
strstream, 941 
strstreambuf, 945-946 
Control messages, 14 
Control menu 
allowing application access to, 699 
called when user selects command from, 788—790 
Control Windows classes 
described, 16 
list, 6 
Converting 
characters from ANSI to OEM character set, 576 
characters from OEM to ANSI character set, 588 
client coordinates to screen coordinates, 663 
CString object to lowercase, 586 
CString object to uppercase, 587 
dialog units of rectangle to screen units, 270 


error codes, run-time library to CFileException, 324 


logical to device points, 215 
points, device into logical, 175 
rectangles between CRect and LPRECT, 531 
Coordinates, carets, retrieving, 686 
Copy member function 
CComboBox class, 143 
CEdit class, 286 
Copying 
See also Duplicating 
allowing application access to Control menu for, 
699 
bitmaps, to current device context, 167-169 
CTimeSpan object, 625 
CWnd’s caption title into specified buffer, 704 


dimensions of bounding rectangle of CWnd object, 


703-704 

edit control selection to Clipboard, 286 
fonts, current, typeface name into buffer, 208 
menu item label to buffer, 427 
rectangles 

scrRect to CRect, 531 

to CRect, 523 
regions into CRgn object, 540 
scroll bar position range, 697 
scroll-bar position to specified location, 556 
time source into CTime object, 615 


to Clipboard, combo box edit control selection, 143 


CopyRect member function 


CRect class, 523 


CopyRgn member function 


CRgn class, 540 


index 


cout, predefined stream object, 900 
Counting 
bytes stored in stream buffers, 913 
elements in lists, 485 
items in list box, 361 
number of elements in maps, 380 
CPaintDC class 
data member 
m_hWnd, 500 
m_ps, 500 
described, 498 
member functions 
CPaintDC, 499 
~CPaintDC, 499 
CPaintDC constructor, 499 
CPaintDC destructor, 499 
CPaintDC objects 
creating, 499 
destroying, 499 
painting client area, 500 
CPalette class 
described, 501—502 
member functions 
AnimatePalette, 503 
CPalette, 503 
CreatePalette, 504 
FromHandle, 504 
GetNearestPaletteIndex, 505 
GetPaletteEntries, 349, 505 
ResizePalette, 506 
SetPaletteEntries, 506—507 
CPalette constructor, 503 
CPalette objects 
creating, initializing, 504 
resizing logical palette attached to, 506 
returning pointer to, 504 
CPen class 
described, 508 
member functions 
CPen, 509-510 
CreatePen, 510 
CreatePenIndirect, 510-511 
FromHandle, 511 
CPen constructor, 509-510 
CPen objects 
creating 
constructor, 509 
initializing, 510 
returning pointer to, 511 
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CPoint class 


adding separate values to x and y members, 513 


described, 20, 512 
member functions 
CPoint, 513 
Offset, 514 
operators, 515-516 
CPoint constructor, 513 
CPoint objects, creating, 513 
CPtrArray class, described, 517-518 
CPtrList class, described, 519-520 
Create member function 
CButton class, 128-131 
CComboBox class, 143—146 
CDialog class, 264—265 
CEdit class, 286—289 
CFrameWnd class, 338-339 
CListBox class, 356—359 
CMDIChildWnd class, 397—398 
CMDIFrameWnd class, 403—404 
CMetaFileDC class, 441 
CScrollBar class, 553—555 
CStatic class, 563-566 
CWnd class, 664—665 
CreateBitmap member function 
CBitmap class, 109-110 
CBrush::CreatePatternBrush, 123 
CWnd::CreateCaret, 665 
CreateBitmapIndirect member function 
CBitmap class, 110 
CBrush::CreatePatternBrush, 123 
CreateBrushIndirect member function 
CBrush class, 120-121 
CreateCaret member function 
CWhnd class, 665 
CreateClient member function 
CMDIFrameWnd class, 404 | 
CreateCompatibleBitmap member function 
CBitmap class, 111 
CBrush::CreatePatternBrush, 123 
CreateCompatibleDC member function 
CDC class, 171-172 
CreateDC member function 
CDC class, 172-173 
CreateDIBPatternBrush member function 
CBrush class, 121—122 
CreateDiscardableBitmap member function 
CBitmap class, 112 
CreateEllipticR gn member function 
CRegn class, 541 


CreateEllipticRgnIndirect member function 
CRegn class, 541-542 

CreateEx member function 
CWnd class, 666—670 

CreateFont data member 
CFont class, 330-333 

CreateFontIndirect data member 
CFont class, 334 

CreateGrayCaret member function 
CWnd class, 671 

CreateHatchBrush member function 
CBrush class, 122—123 

CreateIC member function 
CDC class, 173-174 

CreateIndirect member function 
CDialog class, 266—267 
CModalDialog class, 446-447 

CreateMenu member function 
CMenu class, 421 

CreatePalette member function 
CPalette class, 504 

CreatePatternBrush member function 
CBrush class, 123—124 

CreatePen member function 
CPen class, 510 

CreatePenIndirect member function 
CPen class, 510-511 

CreatePolygonRgn member function 
CRgn class, 542 

CreatePolyPolygonRgn member function 
CRegn class, 543 

CreatePopupMenu member function 
CMenu class, 421—422 

CreateRectRgn member function 
CRgn class, 544 

CreateRectRgnIndirect member function 
CRen class, 544 

CreateRoundRectRgn member function 
CRgn class, 545 

CreateSolidBrush member function 
CBrush class, 124 

CreateSolidCaret member function 
CWnd class, 672 

CreateStockObject member function 
CGdiObject class, 345-346 
CREATESTRUCT structure, 78—79 
CMDIFrameWnd::CreateClient, 404 
CWnd::OnCreate, 724-725 
CWnd::OnNcCreate, 762 


Creating 
bitmaps 
device-compatible, 111 
device-dependent memory, 109-110 
discardable, 112 
specified structure, 110 
Creating (continued) 
brushes 
uninitialized object, 119-120 
with bitmap-specified pattern, 123 
with DIB-specified pattern, 121—122 
with hatch style, 122—124 
with specified structure, 120-121 
CArchive objects, 95 
CArchiveException objects, 105 
carets 
gray, 671 
new shape, 665 
solid, 672 
CBitmap objects, 109 
CBrush objects, 119-120 
CButton objects 
constructor, 128 
control, 128-129, 131 
CClientDC objects, 138 
CComboBox objects, 142 
CDC objects, 169 
CDumpContext objects, 275 
CEdit objects 
CEdit::CEdit, 285 
CEdit::Create, 286, 289 
CFile::CFile, 306 
opening file, 313 
CFileException objects, 324 
CFrameWnd objects, 338-339 
CGdiObject objects, 344 
child windows, constructor, 397 
CListBox objects 
CListBox::CListBox, 355 
specifying style, 356-357, 359 
CMDIChildWnd objects, creating and 
attaching, 397 
CMDIFrameWnd objects, 403 
CMemoryException objects, 413 
CMemoryState objects, 54 
CMenu objects, constructor, 420 
CMetaFileDC objects 
constructor, 440 
device context, 441 


Index 


Creating (continued) 


CModalDialog objects 
constructor, 446 
indirectly, 446-447 
CNotSupportedException objects, 449 
CObject objects, 467 
CObject pointer arrays, 454 
CObject pointer lists, 482—483 
combo boxes, 146 
CPaintDC objects, 499 
CPalette objects, 504 
CPen objects 
constructor, 509 
initializing, 510 
CPoint objects, 513 
CRect objects, 524 
CResourceException objects, 536 
CRen objects constructor, 545 
CSize objects, 559 
CStatic objects 
attaching, 563-564 
constructor, 563 
CStdioFile objects, 568 
CString objects, 579 
CString-to-CObject map objects, 379 
CTime objects, 608-609 
CTimeSpan object, 620-621 
CWinApp objects, constructor, 631 
CWindowDC objects, 642 
CWnd objects called when, 724—726 
device contexts, 172-173 
dialog box objects, 264—265 
dialog boxes 
modeless from template, 266-267 
modeless, 264 
elliptical regions 
CRgn::CreateEllipticRgn, 541 
CRgn::CreateEllipticRgnIndirect, 541 
filebuf objects, 833 
fonts 
constructor, 330 
initializing with given structure, 334 
initializing with specified 
characteristics, 330—333 
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frame windows for CMDIFrameWnd object, 403 


fstream objects, 839, 841 
ifstream objects, 847-848 
istream objects, 881 
lostream_init objects, 874 
istream_withassign objects, 888 
istrstream objects, 891 
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Creating (continued) 


MDI client window, 404 
menus 
empty, 421 
pop-up, 421 
ofstream objects, 896-897 
ostream objects, 873 
ostream objects, 903 
ostream_withassign objects, 909 
ostrstream objects, 912 
pens with specified structure, 510 
rectangles, NULL, 529 
regions 
by combination, 539-540 
polygonal, 542 
rectangular, 544 
rectangular, indirect, 545 
series of polygonal, 543 
scroll bars 
constructor, 553 
initializing, 553-555 
stdiobuf objects, 916 
stdiostream objects, 918 
streambuf objects, 936 
strstream objects, 941 
strstreambuf objects, 945 
Window Edit control, CEdit class, 282 
Windows child windows 
constructor, 673 
attaching to CWnd object, 664—665 
windows with extended style, 666-667, 670 


CRect class 


creating NULL rectangle, 529 
described, 20, 521-522 
dimensions, setting, 528 
member functions 
BottomRight, 523 
CopyRect, 523 
CRect, 524 
EqualRect, 525 
Height, 525 
InflateRect, 525-526 
IntersectRect, 526 
IsRectEmpty, 527 
IsRectNull, 527 
OffsetRect, 527-528 
PtInRect, 528 
SetRect, 528-529 
SetRectEmpty, 529 
Size, 529 
TopLeft, 529 


CRectClass (continued) 
member functions (continued) 
UnionRect, 530 
Width, 530 
operators, 531-535 
CRect constructor, 524 
CRect objects, creating, 524 
CResourceException class 
described, 536 
member functions 
CResourceException, 536 
CResourceException constructor, 536 
CResourceException objects, creating, 536 
CRen class 
described, 537-538 
member functions 
CombineR gn, 539-540 
CopyRgn, 540 
CreateEllipticRgn, 541 
CreateEllipticR gnIndirect, 541-542 
CreatePolygonRgn, 542 
CreatePolyPolygonRgn, 543 
CreateRectRgn, 544 
CreateRectR gnIndirect, 544 
CreateRoundRectRgn, 545 
CRegn, 545 
EqualRgn, 546 
FromHandle, 546 
GetR gnBox, 547 
OffsetRgn, 547-548 
PtInRegion, 548 
RectInRegion, 549 
SetRectRgn, 549-550 
CRegn constructor, 545 
CRegn objects 
checking 
equivalent, 546 
if coordinates are within, 548 
if specified rectangle is within, 549 
copying region into, 540 
creating 
by combination, 539-540 
constructor, 545 
handles, 546 
moving stored region, 547 


retrieving bounding rectangle coordinates, 547 


CScrollBar class 
described, 551-552 
member functions 

Create, 553-555 
CScrollBar, 553 


CScrollBar class (continued) 
member functions (continued) 
GetScrollPos, 555 
GetScrollRange, 556 
SetScrollPos, 556-557 
SetScrollRange, 557 
CScrollBar constructor, 553 
CScrollBar objects, creating 
constructor, 553 
initializing, 553-555 
CSize class 
described, 20, 558 
member functions 
CSize, 559 
operators, 560-561 
CSize constructor, 559 
CSize objects, creating, 559 
CStatic class 
described, 562 
member functions 
Create, 563-566 
CStatic, 563 
CStatic constructor, 563 
CStatic objects, creating 
attaching, 563-564 
constructor, 563 
CStdioFile class 
data members 
m_pStream, 571 
described, 567 
member functions 
CStdioFile, 568-569 
~CStdioFile, 569 
ReadString, 569-570 
WriteString, 570 
CStdioFile constructor, 568—569 
CStdioFile destructor, 569 
CStdioFile objects 
creating, 568 
destroying, 569 
reading text into buffer from associated file, 
569-570 
writing data from buffer to associated file, 570 
CString class 
argument passing conventions, 599 
assignment operator, 592 
casting operator, 592 
comparison operators, 596 
concatenation operators 
CString::operator +, 594 
CString::operator +=, 595 
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CString class (continued) 
described, 28, 572-575 
diagnostic dumping and storing to archive, 593 
exception cleanup, 598 
insertion operator, 593 
member functions 
AnsiToOem, 576 
Collate, 576-577 
Compare, 577 
CompareNoCase, 577-578 
CString, 578-579 
~CString, 580 
Empty, 580 
Find, 580-581 
FindOneOf, 581 
GetAt, 581-582 
GetBuffer, 582-583 
GetBufferSetLength, 583-584 
GetLength, 584 
IsEmpty, 584-585 
Left, 585 
LoadString, 585-586 
MakeLower, 586 
MakeReverse, 586 
MakeUpper, 587 
Mid, 587-588 
OemToAnsi, 588 
ReleaseBuffer, 588-589 
ReverseFind, 589 
Right, 589-590 
SetAt, 590 
SpanExcluding, 591 
SpanIncluding, 591 
operators, 592—600 
strings as function inputs, 599 
subscript operator [], 597 
CString constructor, 578-579 
CString destructor, 580 
CString objects 
arrays, CStringArray class described, 601 
converting characters from ANSI to OEM 
character set, 576 
converting characters from OEM to ANSI 
character set, 588 
converting to lowercase, 586 
converting to uppercase, 587 
creating, 579 
destroying, 580 
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CString objects (continued) 


extracting 
first characters from and returning copy, 585 
largest substring excluding specified 
characters, 591 
last characters and returning copy, 589-590 
substring of specified length and returning 
copy, 587 
keyed to CString objects, 389 
list, CStringList class described, 603 
making empty string, 580 
maps to CObject pointers, 377 
overwriting specified character, 590 
reading Windows string resource into, 586 
reinitializing with new data, 592 
returning 
count of characters in, 584 
pointer to internal character buffer and matching 
length, 583-584 
reversing character order in, 586 
searching for last substring match, 589 
terminating use of buffer, 588 
testing for empty condition, 584 


CTimeSpan class 
described, 28, 618-619 
member functions 
CTimeSpan, 620-621 
Format, 621-622 
GetDays, 622 
GetHours, 622 
GetMinutes, 623 
GetSeconds, 623 
GetTotalHours, 623 
GetTotalMinutes, 624 
GetTotalSeconds, 624 
operators, 620-627 
CTimeSpan objects, creating, 620-621 
Current position 
carets 
displaying, 816-817 
getting, 686 
scroll bars 
getting, 696-697 
setting, 811-812 
Cursors 
called on press of mouse button, 758—759 


CStringArray class, described, 601-602 
CStringList class, described, 603-605 
CTime class 


called when moved within nonclient area, 769 
loading, predefined Windows applications, 


described, 28, 606-607 

member functions 
Ctime, 608 
Format, 609 
FormatGmt, 610 
GetCurrentTime, 610 
GetDay, 611 
GetDayofWeek, 611 
GetGmtTm, 611 
GetHour, 612 
GetLocalTm, 613 
GetMinute, 613 
GetMonth, 613 
GetSecond, 614 
GetTime, 614 
Get Year, 614 

operators, 608-617 


CTime object 


adding and subtracting CTimeSpan object, 616 
creating, 608-609 

getting struct tm, returning local time, 612 
getting struct tm, returning UCT, 611 

getting time_t value, 614 

returning current time, 610 


CWinApp::LoadOEMCursor, 634 
CWinApp::LoadStandardCursor, 635 
specified, loading in Windows applications, 633 
Cut member function 
CComboBox class, 146 
CEdit class, 289 
Cutting, Windows Edit control selection, 289 
CWinApp class 
data members 
m_hInstance, 639 
m_hPrevInstance, 639 
m_IpCmdLine, 639 
m_msgCur, 639 
m_nCmdShow, 640, 819 
m_pMainWnd, 640 
m_pszAppName, 640 
described, 11, 628-630 
member functions 
CWinApp, 631 
ExitInstance, 631 
InitApplication, 632 
InitInstance, 632 
LoadCursor, 633, 775 
LoadIcon, 176, 633-634, 775 


CWinApps class (continued) 
member functions (continued) 
LoadOEMCursor, 634 
LoadOEMIcon, 176, 634-635 
LoadStandardCursor, 635-636 
LoadStandardIcon, 176, 636-637 
Onldle, 637 
PreTranslateMessage, 638 
Run, 638 
overridable member functions, 11 
CWinApp constructor, 631 
CWinApp objects 
creating, 631 
returning pointer to, 36 
CWindowDC class 
data members 
m_hWnd, 643 
described, 641 
member functions 
CWindowDC, 642 
~CWindowDC, 642 
CWindowDC objects 
creating, 642 
destroying, 642 
CWnd 
Clipboard, opening, 799 
dialog boxes, searching for previous or next 
control, 693-694 
handles, getting safe, 696 
mouse button, right, 778-780 
nonclient area 
calculating size, 762 
called when destroyed, 763 
CWnd class 
applications, 737 
called when destroyed, 780-781 
confirming choice to terminate, 720 
redrawing or preventing redrawing of 
changes, 811 
attaching HWND, 822 
buttons, 732—735 
buttons, boxes, called when control created, 
754, 756 
called for displaying Clipboard contents, 716-717 
called for mouse capture, 763-764 
called when device-mode settings changed, 731 
called when sessions end, 736 
caption titles 
copying into specified buffer, 704 
returning length, 704 


Index 971 


CWnd class (continued) 


carets 
displaying, 816—817 
moving to position specified by point, 806-807 
client areas 
called after size changed, 784—785 
invalidating, 706 
retrieving pointer to display context, 688 
updating, 819 
validating within rectangle, 820 
Clipboard viewers, called with event in vertical 
scroll bar, 797-798 
combo boxes, comparing items in, 722, 724 
Control menu, called when Maximize or Minimize 
button selected, 788, 790 
control, specifying input type, 739-740 
converting 
client coordinates to screen coordinates, 663 
screen coordinates of point or rect to client 
coordinates, 802 
copying caption into specified buffer, 704 
cursor 
called on press of mouse button, 758-759 
called when moved within nonclient area, 769 
CWinApp message translator, 801 
data members 
m_hWnd, 822 
wndBottom, 822 
wndTop, 822 
described, 644—658 
determining maximization, 711 
device contexts, releasing, 801-802 
enabling or disables mouse or keyboard input, 
68 1-682 
fonts, setting, 809 
input focus 
called after gaining, 783 
called when ALT and another key 
pressed, 791—792 
called with release of key pressed with ALT, 
792-794 
claiming, 809 
specifying character value of dead key, 790-791 
specifying virtual-key code of Control menu key, 
786-787 
invalidating client area, 707 
keyboard, enabling or disabling input, 681-682 
key, returning active, 718—719 
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CWnd class (continued) CWnd class (continued) 


called with keyboard input, 795—796 
retrieving current selection, 679-680 
returning application response, 719-720 


member functions 


ArrangeIconic Windows, 659 
Attach, 659 

BeginPaint, 500, 660 
BringWindowToTop, 661 
ChangeClipboardChain, 661 
CheckDl]gButton, 661-662 
CheckRadioButton, 662 
ChildWindowFromPoint, 662-663 
ClientToScreen, 663 
CloseWindow, 664 

Create, 664—665 

CreateCaret, 665 

CreateEx, 666-670 
CreateGrayCaret, 671 
CreateSolidCaret, 672 

CWnd, 673 

~CWnd, 673 

Default, 673 

DefWindowProc, 674 
DeleteTempMap, 674 

Destroy Window, 265, 267, 675 
Detach, 676 

DlgDirList, 676-677 
DlgDirListComboBox, 678-679 
DigDirSelect, 679-680 
DigDirSelectComboBox, 680-681 
DrawMenuBar, 418, 422, 430, 433-434, 681 
EnableWindow, 681-682 
EndPaint, 682 

FindWindow, 683 

Flash Window, 683-684 
FromHandle, 684 
GetActiveWindow, 685 
GetCapture, 685 

GetCaretPos, 686 
GetCheckedRadioButton, 686 
GetClientRect, 686—687 
GetClipboardOwner, 687 
GetClipboardViewer, 687 
GetCurrentMessage, 688 
GetDC, 174, 688 
GetDesktopWindow, 689 
GetDlgCtrlID, 689 
GetDlgItem, 689-690 
GetDlgItemInt, 690-691 


list boxes member functions (continued) 


GetMenu, 693 
GetDlgItemText, 691 
GetFocus, 692 

GetFont, 692 
GetLastActivePopup, 692-693 
GetNextDlgGroupItem, 693-694 
GetNextDlgTabItem, 694 
GetNextWindow, 695 
GetParent, 696 
GetSafeHwnd, 696 
GetScrollPos, 696-697 
GetScrollRange, 697 
GetStyle, 698 
GetSuperWndProcAddr, 698 
GetSysModalWindow, 698 
GetSystemMenu, 699 
GetTopWindow, 700 
GetUpdateRect, 700-701 
GetUpdateRgn, 701 
GetWindow, 702 
GetWindowDC, 703 
GetWindowRect, 703-704 
GetWindowText, 704 
GetWindowTextLength, 704—705 
HideCaret, 705 
HiliteMenultem, 705—706 
Invalidate, 706—707 
InvalidateRect, 302, 707 
InvalidateRgn, 708 

IsChild, 709 
IsDlgButtonChecked, 709 
IsIconic, 710 
IsWindowEnabled, 710 
IsWindow Visible, 710 
IsZoomed, 711 

KillTimer, 711 

MessageBox, 711-714 
MoveWindow, 714—715 
OnActivate, 715 
OnActivateApp, 716 
OnAskCbFormatName, 716-717 
OnCancelMode, 717 
OnChangeCbChain, 717-718 
OnChar, 718-719 
OnCharToltem, 719-720 
OnChildActivate, 720 
OnClose, 720 

OnCommand, 721 
OnCompacting, 722 
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CWnd class (continued) 
member functions (continued) 


CWhnd class (continued) 
member functions (continued) 


OnCompareltem, 722—724 
OnCreate, 724-726 
OnCtlColor, 726-727 
OnDeadChar, 727—729 
OnDeleteItem, 729-730 
OnDestroy, 730 
OnDestroyClipboard, 731 
OnDevModeChange, 731 
OnDrawClipboard, 731-732 
OnDrawltem, 732-735 
OnEnable, 735—736 
OnEndSession, 736 
OnEnterldle, 737 
OnEraseBkgnd, 737-738 
OnFontChange, 738-739 
OnGetDlgCode, 739-740 
OnGetMinMaxInfo, 740-741 
OnHScroll, 741-742 
OnHScrollClipboard, 742-743 
OnlIconEraseBkend, 743 
OnInitMenu, 744 
OnInitMenuPopup, 744-745 
OnKeyDown, 745-746 
OnKeyUp, 746-747 
OnkKillFocus, 747-748 
OnLButtonDbIClk, 748-749 
OnLButtonDown, 749 
OnLButtonUp, 750 
OnMButtonDbIClk, 751 
OnMButtonDown, 752 
OnMButtonUp, 752-753 
OnMDtIActivate, 753-754 
OnMeasureltem, 754—756 
OnMenuChar, 756-757 
OnMenuSelect, 757—758 
OnMouseActivate, 758—759 
OnMouseMove, 760 
OnMove, 760-761 
OnNcActivate, 761 
OnNcCalcSize, 762 
OnNcCreate, 762—763 
OnNcDestroy, 763 
OnNcHitTest, 763—764 
OnNcLButtonDbIClk, 765 
OnNcLButtonDown, 765—766 
OnNcLButtonUp, 766 
OnNcMButtonDbIClk, 767 
OnNcMButtonDown, 767-768 
OnNcMButtonUp, 768 


OnNcMouseMove, 769 
OnNcPaint, 769 
OnNcRButtonDbIClk, 770 
OnNcRButtonDown, 770-771 
OnNcRButtonUp, 771 
OnPaint, 772 
OnPaintClipboard, 773 
OnPaintClipboard, 772-773 
OnPainticon, 773 
OnPaletteChanged, 773-774 
OnParentNotify, 774-775 
OnQueryDragIcon, 775-776 
OnQueryEndSession, 776 
OnQueryNewPalette, 777 
OnQueryOpen, 777 
OnRButtonDbI!Clk, 778 
OnRButtonDown, 779 
OnRButtonUp, 780 
OnRenderAllFormats, 780-78 1 
OnRenderFormat, 78 1 
OnSetCursor, 782 
OnSetFocus, 783 

OnShow Window, 783-784 
OnSize, 784-785 
OnSizeClipboard, 785 
OnSpoolerStatus, 786 
OnSysChar, 786-787 
OnSysColorChange, 788 
OnSysCommand, 788-790 
OnSysDeadChar, 790-791 
OnSysKeyDown, 791-792 
OnSysKeyUp, 792-794 
OnTimeChange, 794 
OnTimer, 795 
OnVKeyToltem, 795-796 
OnVScroll, 796—797 
OnVScrollClipboard, 797-798 
OnWinIniChange, 798-799 
OpenClipboard, 799 
OpenIcon, 800 
PostMessage, 800-801 
PreTranslateMessage, 801 
ReleaseDC, 174, 801-802 
ScreenToClient, 802 
ScrollWindow, 803-804 
SendDlgItemMessage, 804 
SendMessage, 805 
SetActiveWindow, 805-806 
SetCapture, 806 
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CWnd class (continued) 


member functions (continued) 

SetCaretPos, 806—807 

SetClipboard Viewer, 807 

SetDlgItemInt, 808 

SetDlgItemText, 808 

SetFocus, 809 

SetFont, 809 

SetMenu, 810 

SetParent, 810 

SetRedraw, 811 | 

SetScrollPos, 811—812 

SetScrollRange, 812-813 

SetSysModal Window, 813 

SetTimer, 813-814 

SetWindowPos, 814—816 

SetWindowText, 297, 816 

ShowCaret, 816—817 

ShowOwnedPopups, 817 

ShowScrollBar, 817-818 

Show Window, 640, 818-819 

Update Window, 819 

ValidateRect, 820 

ValidateRgn, 820 

WindowFromPoint, 821 

WindowProc, 821 
menu item, called when control created, 754, 756 
menu mnemonic character, called when user 

presses, 756—757 

menus, setting current to specified, 810 
message handling upon selection of item, 721 
messages, sending to specified control, 804 
minimizing, 664 
mouse button, left 

called when double-clicked in nonclient area, 765 

called when pressed, 749 

called when pressed in nonclient area, 765—766 

called when released, 750 
mouse button, middle 

called when double-clicked, 751 

called when double-clicked in nonclient area, 767 

called when pressed, 752 

called when pressed in nonclient area, 767—768 

called when released, 752—753 

called when released in nonclient area, 766—768 
mouse button, right 

called when double-clicked within nonclient 

area, 770 
called when pressed within nonclient 
area, 7/0—771 
called when released within nonclient area, 771 


CWnd class (continued) 


mouse capture, retrieving, 685 
mouse cursor 
called when input isn’t captured, 782 
called when moved, 760 
mouse enumerated values (list), 88 
mouse input, causing all subsequent to be sent to 
current object, 806 
mouse, enabling or disabling input, 681-682 
nonclient area, called when needing painting, 769 
nonsystem key 
called on input, 745-746 
called on release, 746—747 
painting 
called when repainting, 772 
preparing for, 660 
Print Manager, called when job added or deleted 
from queue, 786 
removing windows from Clipboard viewer chain, 
717-718 
returning specified class, 683 
scroll bars 
hiding, 817-818 
setting range of position values, 812-813 
vertical, called when clicked, 796-797 
scroll boxes, setting to specified position, 811-812 
setting 
control text owned by CWnd, 808 
control text to specified integer value, 808 
system time, called after change, 794 
window-manager’s list, searching for windows, 702 
windows 
containing given point, identifying, 821 
making active, 805—806 
specifying memory compaction time, 722 
Windows initialization file, called after change 
made, 798—799 
Windows windows 
attaching to CWnd object, 659 
returning maximized position or 
dimensions, or tracking size range, 740-741 
windows, child 
called on activation or deactivation, 753-754 
changing parent, 810 
constructor, 673 
creating and attaching to object, 664-665 
creating with extended style, 666-670 
windows, pop-up, showing or hiding, 817 
WS_TABSTOP style control, retrieving 
pointer to, 694 


CWnd constructor, 673 


CWnd destructor, 673 
CWnd objects 


button control, determining if check-marked, 709 
called after CWnd moved, 760-761 
called when about to be shown or hidden, 783-784 
called when activating for different task, 716 
called when activating or deactivating, 715 
called when application creates, 724—726 
called when background needs erasing, 737-738 
called when enabled state is changed, 735-736 
changing position and dimensions, 714-715 
copying dimensions of bounding 
rectangle, 703-704 
creating, called prior to WM_CREATE 
message, 762—763 
deleting temporary, CWnd::DeleteTempMap, 674 
destroying 
CWnd::~CWnd, 673 
called to inform, CWnd::OnDestroy, 730 
detaching Windows handle, 676 
displaying CWnd, 818-819 
enabling for mouse and keyboard input, 710 
iconized, called when user requests open 
window, 777 
ID, returning, 689 
input focus, called before losing, 747-748 
making into system-modal window, 813 
menu items, called when user selects, 757-758 
messages, placing in queue, 800 
minimized, called when background must be filled 
before painting, 743 
minimizing, 710 
moving to end of window list, 822 
moving to top of window list, 822 
providing Windows procedure for, 821 
returning pointer to when given handle to window, 
684 
scrolling, 803-804 


with focus, displaying dialog or message boxes, 717 


called when double-clicked, 748—749 


CWordArray class, described, 823-824 


D 


Data 


archive 
determining if loading, 98 
determining if storing, 98 
extracting from streams, 878, 880 
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Days 
of month, 611 
of week, 611 
hours in current, getting, 622 
span, getting, 622 
dbp member function, streambuf class, 923 
Dead keys 
defined, 728 
returning character value, 727-729 
specifying character value, 790-79 1 
Debug environment, assertions, 29 
Debugging 
controlling memory allocator, afxMemDF 
variable, 46 
DEBUG_NEW macro, 38 
Debugging (continued) 
diagnostic memory tracking, 49 
diagnostic services described, 28 
tuning allocation diagnostics, 46 
writing ASCII information on stdout, 923 
DEBUG_NEW macro, 38 
DECLARE DYNAMIC macro, 38-39, 468 
DECLARE_ SERIAL macro, 39-40, 468 
Default member function 
CWnd class, 673 
DefWindowProc member function 
CWnd class, 674 
delbuf member function 
10s class, 856—857 
DeleteDC member function 
CDC class, 174—175 
DELETEITEMSTRUCT structure, 80 
CWnd::OnDeleteltem, 729 
DeleteMenu member function 
CMenu class, 422 
DeleteObject member function 
CGdiObject class, 346-347 
CDialog::OnSetFont, 272 
DeleteString member function 
CComboBox class, 147 
CWnd::OnDeleteltem, 729 
CListBox class, 359 
CWnd::OnDeleteltem, 729 
DeleteTempMap member function 
CGdiObject class, 347 
CWnd class, 674 
Deleting 
CGdiObject object, 346 
CGdiObject, temporary, 347 


combo boxes, edit control selection, 143, 146 
device contexts attached to CDC object, 174 
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Deleting (continued) 
files specified by path, 315 
items from list or combo boxes, called 
when, 729-730 
menu items, 422 
strings 
from list boxes, 359 
list box in combo box, 147 
temporary CWnd objects, 674 
Windows DC attached to CDC object, 174 
Derivation of classes, 10 
Design philosophy, Foundation class library, 7-8 
Desktop window, returning, 689 
Destroying 
CArchive objects, 96 
CClientDC objects, 138 
CDC objects, 170 
CFrameWnd objects, 338 
CGdiObject objects, 345 
CMapStringToOb objects, 379 
CMenu objects, 421 
CObject objects, 467 
CObject pointer array, 454 
CObject pointer lists, 483 
CPaintDC objects, 499 
CStdioFile objects, 569 
CString objects, 580 
CWindowDC objects, 642 
CWnd objects, called to inform, 
CWnd::OnDestroy, 730 
CWnd::~CWnd, 673 
fstream objects, 841 
ifstream objects, 849 
1ostream objects, 873 
Iostream_init objects, 874 
istream objects, 882 
istream_withassign objects, 888 
istrstream objects, 891 
list or combo box, called to inform owner, 729-730 
MDI child windows, 399 
menus, 423 
ofstream objects, 897 
ostream objects, 903 
ostream_withassign objects, 909 
ostrstream objects, 913 
stdiobuf objects, 916 
stdiostream objects, 918 
streambuf objects, 936 
strstream objects, 942 
strstreambuf objects, 946 
Windows windows, attached to CWnd, 675 


DestroyMenu member function 


CMenu class, 423 
CWnd::SetMenu, 810 


DestroyWindow member function 


CWnd class, 675 
CDialog::Create, 265 
CDialog::CreateIndirect, 267 


Destructors 


CArchive, 96 
CClientDC, 138 
CDC, 170 

CFile, 308 
CFrameWnd, 338 
CGdiObject, 345 
CMapStringToOb, 379 
CMemFile, 412 
CMenu, 421 
CObAtrray, 454 
CObject, 467 
CObList, 483 
CPaintDC, 499 
CStdioFile, 569 
CString, 580 
CWnd, 673 
filebuf, 834 
fstream, 841 
ifstream, 849 

108, 860 

iostream, 873-874 
istream, 882, 888-889 
istrstream, 891 
ofstream, 897 
ostream, 903, 909 
ostrstream, 913 
stdiobuf, 916 
stdiostream, 918 
streambuf, 936 
strstream, 942 
strstreambuf, 946 


Detach member function 


CGdiObject class, 347 
CMenu class, 423 
CWnd class, 676 


Detaching 


Windows GDI object, 347 
Windows menu from CMenu object, 423 


Device contexts 


bit pattern, creating, 218-219 
brushes, retrieving orign of current, 193 
checking BitBlt support, 169 


Device contexts (continued) 
classes generally, 18 
classes (list), 6 
client areas 
CClientDC class described, 137 
retrieving pointer to, 688 
clipping region, specifying whether point is 
within, 223 
copying bitmap to current, 167, 169 
CPaintDC class described, 498 
creating CDC objects, 171 
CDC::CreateDC, 172-173 
CWindowDC class described, 641 
informing of new print job, 254 
metafile, closing and creating handle to play, 440 
objects, CDC class described, 156 
operations described, 156 
palettes, selecting logical, 233 
pens, brushes, enumerating available, 182—184 
releasing, 801—802 
retrieving x- and y-coordinates 
of associated window, 209 
viewport origin, 209 
windows origin, 210 
saving current state, 227 
selecting GDI object into, 18 
selecting object into, 232—233 
setting viewport origins, 251 
setting window origin, 253 
text-alignment flags, retrieving status, 205 
translation origin, obtaining, 196 
viewports 
retrieving x- and y-extents, 209 
setting x- and y-extents, 250 
Windows, restoring to previous state, 226 
Devices 
applications, allowing access to, 184-185 
contexts, creating, 172-173 
creating 
information context for, 173 
memory device context, 171 
Diagnostic dump context described, 24 
Diagnostic dumping 
and storing to archive 617 
time spans, 627 
Diagnostic output 
stream-oriented, human readable, CDumpContext 
class described, 273 
Diagnostic services 
ASSERT macro, 53 
assertions, 29 
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Diagnostic services (continued) 


checking for corrupt guard bytes, 47 
described, 28-29 
executing specified iteration, function for 
CObject-derived classes, 48, 49 
forcing program halt on specified sequence 
numbers, 52 
macros and global functions 
described, 43, 46-49, 51-57 
output, 29 
printing memory statistics report, 56 
setting hook for memory allocation, 51 
testing 
ensuring memory block is contained in 
program’s memory space, 51 
memory address, 50 
tracking memory, 49 
tuning allocation diagnostics, 46 


Diagnostics, memory, described, 29 
Dialog box objects, constructing, 264—265 
Dialog boxes 


called to inform main window when entering idle 
State, 737 
construction and use, 17 
control 
returning pointer to specified, 689-690 
converting units of rectangle to screen units, 270 
creating 
building resource, 262 
from resource template, 261 
CWnd, called to cancel other modes, 717 
defined, 17 
defining in resource files, 17 
described, 261 
focus control 
CDialog::GotoDlgCtrl, 268 
CDialog::NextDlgCtrl, 270 
previous, 272 
fonts 
for drawing text, 271 
setting on the fly, 262 
invoking and returning result, 447 
message-checking, 268—269 
modal 
Cancel button action overriding, 448 
CModalDialog class described, 443-444 
constructor, 446 
creating indirect, 446-447 
explained, 17 
invoking and returning result, 447 
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Dialog boxes (continued) 
modal (continued) 
OK button, overriding, 448 
terminating, 267 
modeless 
constructor, 264 
creating, 261 
creating, 266—267 
described, 261 
explained, 17 
overriding member functions, 261 
push button control, getting ID, 268 
retrieving associated caption or text, 691 


searching for previous or next control, 693-694 


standard procedure, 271 


translating text of specified control into integer 


value, 690-691 
Dialog, windows, classes (list), 6 
Dir member function 
CComboBox class, 147-148 
CListBox class, 360 
Directories 
adding to list boxes, 360 
putting 
in combo boxes, 678-679 
in list boxes, 676-677 
Disk file input, ifstream class described, 845 
Display 
contexts, retrieving for entire window, 703 
devices, returning information about, 196, 201 
DlgDirList member function 
CWnd class, 676-677 
DlgDirListComboBox member function 
CWnd class, 678—679 
DigDirSelect member function 
CWnd class, 679-680 
DlgDirSelectComboBox member function 
CWnd class, 680-68 1 
doallocate member function 
streambuf class, 923 
DoModal member function 
CModalDialog class, 447 
DPtoLP member function 
CDC class, 175 
Dragging minimized CWnd, 775 
DrawFocusRect member function 
CDC class, 175-176 
DrawIcon member function 
CDC class, 176 


Drawing 
borders 
around rectangles, 191 
around regions, 192 
chords, 170-171 
ellipses, 179-180 
elliptical arcs, 165-166 
formatted text in rectangle, 177-179 
icons on CDC device, 176 
line segments, 222 
lines, 214 
pie-shaped wedges, 219-220 
polygons 
CDC::Polygon, 221 
CDC::PolyPolygon, 222 | 
preventing in invalid window area, 186 
rectangles 
CDC::Rectangle, 224 
style indicating focus, 175 
with rounded corners, 226-227 
retrieving current mode, 203 
setting mode, 243-244 
text 
dimmed, 210—212 
setting font in dialog boxes, 271 
DRAWITEMSTRUCT structure, 81-83 
CWnd::OnDrawltem, 732—733 
DrawMenuBar member function 
CWnd class, 681 
CMenu::AppendMenu, 418 
CMenu::DeleteMenu, 422 
CMenu::InsertMenu, 430 
CMenu::ModifyMenu, 433 
CMenu::RemoveMenu, 434 
DrawText member function 
CDC class, 177-179 
Drives, adding to list boxes, 360 
Dump member function 
CObject class, 469-470 
CDumpContext::operator <<, 278-279 
CObject::Dump, 469 
Dumping 
array of hexadecimal-formatted bytes, 276 
depth 
getting, 276 
setting, 277 


flushing data to file attached to dump context, 275 


matching reported corrupted memory with 
contents, 55 
objects to CObject objects, 469—470 


Duplicate member function 
CFile class, 309 
Duplicating CFile object, 309 
Dynamic character strings, CString class 
described, 28 


E 


eatwhite member function 
istream class, 877 
eback member function 
streambuf class, 924 
ebuf member function 
streambuf class, 924 
Edit control 
See also Multiple-line edit control 
characters, selecting range, 301 
combo boxes, getting position of current selection, 
149 
current selection 
getting starting, ending character positions, 293 
replacing with text, 297 
determining if contents modified, 292 
getting formatting rectangle, 293 
line length, retrieving, 295 
maximum text length, specifying, 294 
modification flag setting, clearing, 298 
multiple-line. See Multiple-line edit control 
password character, setting, removing, 299 
pasting data to, 297 
undoing last operation, 302 
Edit operations, undoing, 285 
egptr member function 
streambuf class, 924 
ElementAt member function 
CObArray class, 454-455 
Ellipse member function 
CDC class, 179-180 
Ellipses 
creating region, 541 
drawing, 179-180 
Elliptical arcs, drawing, 165-166 
Empty member function 
CString class, 580 
Empty UndoBuffer member function 
CEdit class, 290 
EnableMenultem member function 
CMenu class, 423-424 
EnableWindow member function 
CWnd class, 681-682 
Enabling menu items, 423-424 
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END_CATCH macro, 66 
EndDialog member function 
CDialog class, 267 
EndDoc member function 
CDC class, 180-181 
Ending session, called when, 776 
EndPage member function 
CDC class, 181-182 
EndPaint member function 
CWnd class, 682 
EnumObjects member function 
CDC class, 182-184 
eof member function 
ios class, 857 
epptr member function 
streambuf class, 925 
EqualRect member function 
CRect class, 525 
EqualRgn member function 
CRgn class, 546 
ErrnoToException data member 
CFileException class, 324—325 
Error bits 
setting or clearing, 856 
testing if clear, 859 
Error testing, I/O, 857 
Errors 
converting run-time library values to 
CFileException values, 324 
I/O, testing for serious, 855 
operating system, 328 
Escape member function 
CDC class, 184-185 
Evaluating, arguments 
ASSERT macro, 53 
VERIFY macro, 57 
Exception handling 
described, 30 
exception classes and macros described, 30 
when to use, 30 
Exception processing, 59, 67 
AfxAbort, 61 
AfxSetTerminate, 61 
AfxTerminate, 62 
AfxThrowArchiveException, 63 
AfxThrowMemoryException, 64 
AfxThrowNotSupportedException, 64 
AfxThrowResourceException, 64 
AND_CATCH macro, 65 
CNotSupportedException class described, 449 
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Exception processing (continued) 
defining block of code for catching 
additional exception types, 
AND_CATCH macro, 65 
first exception type, CATCH macro, 65 
END_CATCH macro, 66 
marking end of last CATCH block, 
END_CATCH macro, 66 
termination 
default function, 61 
fatal error, 62 
linking to specified function, 61 
THROW macro, 66 
throwing 
CArchiveException, 63 
CFileException, 63 
CMemoryException, 64 
CNotSupportedException, 64 
CResourceException, 64 
identifying code that might, 67 
rethrowing back to next outer CATCH block, 67 
specified exception, 66 
TRY macro, 67 
Exceptions 
throwing 
CMemoryException, 64 
CResourceException, 64 
CException class described, 303 
CFileException 
class described, 322 
objects, creating, 324 
CNotSupportedException class described, 449 
macros and global functions described, 59-67 
memory, CMemoryException objects, 413 
resources, CResourceException class 
described, 536 
throwing 
CArchiveException, 63 
CFileException::ThrowOsError, 326 
CFileException, AfxThrowFileException, 63 
CNotSupportedException, 64 
ExcludeClipRect member function 
CDC class, 185-186 
ExcludeUpdateRgn member function 
CDC class, 186 
ExitInstance member function 
CWinApp class, 631 
ExitInstance, overridable member function, 11 
ExtFloodFill member function 
CDC class, 187—188 
Extracting white space from streams, 886 


Extraction operator 


CArchive class, 102 
CString class, 593 
CTime class, 617 
CTimeSpan class, 627 
istream class, 885 


ExtTextOut member function 


F 


CDC class, 188-189 


fail member function 


10S class, 857 


fd member function 


filebuf class, 833 
fstream class, 839 
ifstream class, 847 
ofstream class, 895 


File classes described, 26 
File descriptors 


associated with streams, returning, 839, 847 
returning for filebuf object, 833 
streams, returning, 895 


File pointers 


current position, obtaining, 310 
repositioning, 316—317 
setting value 

to beginning of file, 317 

to logical end of file, 317 


filebuf class 


consume defined, 927 
described, 831 
member functions 
attach, 832 
close, 832, 838, 846, 894 
fd, 833 
filebuf, 833 
~filebuf, 834 
is_open, 834 
open, 834-835 
setmode, 835 


ilebuf constructor, 833 
filebuf destructor, 834 
filebuf objects 


attaching specified reserve area to stream’s, 850 

buffer associated with stream, returning pointer to, 
850 

calling closing associated file, 838 

closing and disconnecting, 846 

closing connected file, 834 
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filebuf objects (continued) Files (continued) 
connecting to specified open file, 832 operating system, closing, 308 
constructor, 847-848 pointers 
creating, 833 getting current position, 310 
destroying, 849 repositioning, 316-317 
disconnecting file from and flushing, 832 setting value to beginning of file, 317 
fstream constructor, 839, 841 setting value to logical end of file, 317 
opening disk file for stream, 849 reading data into buffers, 314 
opening file and connecting, 834-835 renaming, 315 
reserve area, attaching, 843 run-time stream, CStdioFile class described, 567 
returning associated file descriptor, 833 status 
setting binary/text mode, 835 CFile object, 310-311 
setting binary/text mode, 844 setting, 318 
streams, 898 testing for connection to open, 834 
attaching specified reserve area, 899 unlocking range of bytes, 319 
closing, 894 writing, associated with CFile object, 320 
opening file for attachment, 898 fill member function 
testing for connection to open disk file, 834 10s class, 857-858 
Filenames, adding to list box of combo box, 147 FillRect member function 
Files CDC class, 189-190 
beginning, setting file pointers to, 317 FillRgn member function 
buffers, flushing, 309 CDC class, 190 
CFile class described, 304 Find member function 
closing CObList class, 483-484 
associated with CFile object, 308 CString class, 580-581 
filebuf objects, 834 FindIndex member function 
Operating system, 308 CObList class, 484 
creating, 306 Finding strings in list boxes, 361 
deleting specified by path, 315 FindOneOf member function 
directories, putting in combo boxes, 678-679 CString class, 581 
putting in list boxes, 678-677 FindString member function 
disconnecting from filebuf object, 832 CComboBox class, 148 
duplicating CFile object, 309 CListBox class, 361 
end of FindWindow member function 
setting file pointers to, 317 CWnd class, 683 
testing, 857 Flags 
length buffer-deletion, assigning value for stream, 856 
changing, 318 edit control undo, resetting, 290 
obtaining in bytes, 309 error-state, setting or clearing, 856 
locking range of bytes, 312 format 
memory clearing, 864 
closing, 412 flag bits, defining, 855 
opening, 412 setting specified format bits, 863 
open stream’s internal variable, setting, 858-859 
testing for attachment to stream, 842, 849, 895 text-alignment 
opening retrieving status for device context, 205 
for attachment to stream’s filebuf object, 842 specifying, 246-247 
for CFile objects, 313 undo. See Undo Flags. 
for connection to filebuf objects, 834-835 flags member function 


operating system handle, 321 10S Class, 858—859 
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Flashing 
carets, 816-817 
window once, 683-684 
FlashWindow member function 
CWnd class, 683-684 
floatfield data member 
10s class, 867 
Floating point 
format flag bits, obtaining, 867 
precision variable 
setting for stream, 870 
setting, 861 
FloodFill member function 
CDC class, 190-191 
Flush member function 
CArchive class, 97 
CFile::Flush, 309 
CDumpContext class, 275 
CFile class, 309 
flush member function 
ostream class, 902 
Flushing 
buffers to dump context, 275 
file buffers, 309 
output buffers, 907 
stream buffers, 902 
FmtLines member function 
CEdit class, 290 
Focus control of dialog boxes 
moving to specified control, 268 
next, 270 
previous, 272 
Fonts 
aspect-ratio filter, 192 
called upon change, 738~—739 
CFont class described, 329 
copying typeface name into buffer, 208 
creating, 330 
current, retrieving, 692 
dialog boxes, 271 
dialog boxes, setting on the fly, 262 
initializing 
LOGFONT-specified characteristics, 334 
specified characteristics, 330-333 
mapper, altering, 241 
predefined, retrieving handle to, 345-346 
selecting, 442 
retrieving character widths, 194 
retrieving metrics for current, 208 
returning pointer to CFont object, 335 
setting CWnd, 809 


Format 
conversion base, setting to 10, 868 
conversion base, setting to 16, 868 
conversion base, setting to 8, 869 
flag bits, defining, 855 
Format bits, setting, 863 
Format flags 
clearing, 864 
streams 
clearing specified, 869 
setting, 870 
Formats 
Clipboard (list), 86—87 
Clipboard, called for delayed rendering, 781 
Formatting rectangles, edit control 
getting, 293 
setting, 299 
Foundation class library design philosophy, 7-8 
Foundation classes 
collection classes described, 26—27 
derivation, 10 
general purpose, described, 21—30 
message processing, vs. native Windows, 9 
miscellaneous support classes described, 28 
polymorphism, 10 
special WinMain version, 12 
vs. native Windows program initialization, 12 
Frame windows 
CFrameWnd class described, 336 
child, getting, 339 
classes (list), 6 
creating 
attaching, 338-339 
constructor, 338 
MDI client window, 404 
MDI constructor, 403 
destroying, 338 
loading accelerator table, 340 
replacing menu of MDI, 408-409 
returning active MDI child, 405 
FrameRect member function 
CDC class, 191 
FrameRgn member function 
CDC class, 192 
FreeExtra member function 
CObArray class, 455 
freeze member function 
strstreambuf class, 944 
FromHandle data member 
CFont class, 335 


FromHandle member function 
CBitmap class, 113 
CBrush class, 125 
CGdiObject class, 348 
CPalette class, 504 
CPen class, 511 
CRgn class, 546 
CWnd class, 684 

fstream class 
described, 836-837 
member functions 

attach, 838 
close, 838 

fd, 839 

fstream, 839-841 
~fstream, 841 
is_open, 842 
open, 842 

rdbuf, 843 
setbuf, 843 
setmode, 844 

fstream constructor, 839-841 

fstream destructor, 841 

fstream objects, creating, 839-841 
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gbump member function 
streambuf class, 925 
gcount member function 
istream class, 877 
GDI 
classes 
described, 18 
list, 6—7 
device contexts 
classes (list), 6 
specifying origin for next brush assignment, 239 
drawing objects classes (list), 6 
object classes described, 18 
raster-operation codes (list), 167-168 
GDI bitmaps 
CBitmap class described, 107—108 
GDI objects 
attaching, 344 
CGdiObject class described, 342 
get areas 
returning lower bound, 924 
returning number of characters available for 
fetching, 926 
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get areas (continued) 
returning pointer to byte after last, 924 
setting pointer values, 932 
get member function 
istream class, 878-879 
Get pointers 
advancing after returning current character, 929 
following fetched characters, 933 
getting value of, 884 
incrementing, 925 
moving back, 934 
moving forward one character, 935 
returning character at, 933 
returning to next character to be fetched from, 925 
testing, 934 
GetActiveWindow member function 
CWhnd class, 685 
GetAspectRatioFilter member function 
CDC class, 192 
GetAt member function 
CObaArray class, 455 
CObList class, 485 
CString class, 581-582 
GetBitmapBits member function 
CBitmap class, 113 
CGdiObject::GetObject, 349 
GetBitmapDimension member function 
CBitmap class, 114 
GetBkColor member function 
CDC class, 193 
GetBkMode member function 
CDC class, 193 
GetBrushOrg member function 
CDC class, 193-194 
GetBuffer member function 
CString class, 582-583 
GetBufferSetLength member function 
CString class, 583-584 
GetButtonStyle member function 
CButton class, 131 
GetCapture member function 
CWnd class, 685 
GetCaretPos member function 
CWnd class, 686 
GetCharWidth member function 
CDC class, 194 
GetCheck member function 
CButton class, 132 
GetCheckedRadioButton member function 
CWnd class, 686 
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GetChildFrame member function 
CFrameWnd class, 339 
CMDIFrameWnd class, 405 

GetClientRect, 687 
CWnd class 

CWnd::GetClientRect, 687 

GetClientRect member function 
CWnd class, 686—687 

GetClipboardOwner member function 
CWnd class, 687 

GetClipboard Viewer member function 
CWnd class, 687 

GetClipBox member function 
CDC class, 195 

GetCount member function 
CComboBox class, 149 
CListBox class, 361 
CMapStringToOb class, 380 
CObList class, 485-486 

GetCurrentMessage member function 
CWnd class, 688 

GetCurrentPosition member function 
CDC class, 195 

GetCurSel member function 
CComboBox class, 149 
CListBox class, 362 

GetDayOfWeek member function 
CTime class, 611 

GetDC member function 
CWhnd class, 688 

CDC::DeleteDC, 174 

GetDCOrg member function 
CDC class, 196 

GetDefID member function 
CDialog class, 268 

GetDepth member function 
CDumpContext class, 276 

GetDesktopWindow member function 
CWnd class, 689 

GetDeviceCaps member function 
CDC class, 196-201 

GetDlgCtr1ID member function 
CWnd class, 689 

GetDlgItem member function 
CWnd class, 689-690 

GetDlgItemInt member function 
CWnd class, 690-691 

GetDlgItemText member function 
CWnd class, 691 

GetEditSel member function 
CComboBox class, 149 


GetFile member function 
CArchive class, 97 
GetFocus member function 
CWnd class, 692 
GetFont member function 
CWhnd class, 692 
GetHandle member function 
CEdit class, 291 
GetHead member function 
CObList class, 486—487 
GetHeadPosition member function 
CObList class, 487 
GetHorizontalExtent member function 
CListBox class, 362 
GetItemData member function 
CComboBox class, 150 
CListBox class, 363 
GetItemRect member function 
CListBox class, 363 
GetLastActivePopup member function 
CWnd class, 692-693 
GetLBText member function 
CComboBox class, 150 
GetLBTextLen member function 
CComboBox class, 151 
GetLength member function 
CFile class, 309 
CString class, 584 
GetLine member function 
CEdit class, 291—292 
istream class, 879-880 
GetLineCount member function 
CEdit class, 292 
GetMapMode member function 
CDC class, 201 
GetMenu member function 
CWnd class, 693 
GetMenultemCount member function 
CMenu class, 424 
GetMenulItemID member function 
CMenu class, 425 
GetMenuState member function 
CMenu class, 425-426 
GetMenuString member function 
CMenu class, 427 
GetModify member function 
CEdit class, 292—293 
GetNearestColor member function 
CDC class, 202 
GetNearestPaletteIndex member function 
CPalette class, 505 


GetNext member function 
CObList class, 488—489 
GetNextAssoc member function 
CMapStringToOb class, 380-381 
GetNextDlgGroupItem member function 
CWnd class, 693-694 
GetNextDlgTabItem member function 
CWnd class, 694 
GetNextWindow member function 
CWnd class, 695 
GetObject member function 
CGdiObject class, 348-349 
GetPaletteEntries member function 
CPalette class, 505 
CGdiObject::GetObject, 349 
GetParent member function 
CWhnd class, 696 
GetParentFrame member function 
CFrameWnd class, 340 
CMD IChildWnd class, 398 
GetPixel member function 
CDC class, 202—203 
GetPolyFillMode member function 
CDC class, 203 
GetPosition member function 
CFile class, 310 
GetPrev member function 
CObList class, 489-490 
GetRect member function 
CEdit class, 293 
GetRgnBox member function 
CRen class, 547 
GetROP2 member function 
CDC class, 203 
GetRuntimeClass member function 
CObject class, 470-471 
GetSafeHandle member function 
CGdiObject class, 349 
GetSafeHwnd member function 
CWnd class, 696 
GetScrollPos member function 
CScrollBar class, 555 
CWnd class, 696-697 
GetScrollRange member function 
CScrollBar class, 556 
CWnd class, 697 
GetSel member function 
CEdit class, 293 
CListBox class, 364 
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GetSelCount member function 
CListBox class, 364 
GetSelltems member function 
CListBox class, 364-365 
GetSize member function 
CObaArray class, 456 
GetStartPosition member function 
CMapStringToOb class, 381 
GetState member function 
CButton class, 132—133 
GetStatus member function 
CFile class, 310-312 
GetStretchBltMode member function 
CDC class, 204 
GetStyle member function 
CWnd class, 698 
GetSubMenu member function 
CMenu class, 428 
GetSuperWndProcAddr member function 
CWnd class, 698 
GetSysModalWindow member function 
CWnd class, 698 
GetSystemMenu member function 
CWnd class, 699 
GetTabbedTextExtent member function 
CDC class, 204—205 
GetTail member function 
CObList class, 490 
GetTailPosition member function 
CObList class, 491 
GetText member function 
CListBox class, 365 
GetTextAlign member function 
CDC class, 205—206 
GetTextCharacterExtra member function 
CDC class, 206 
GetTextColor member function 
CDC class, 207 
GetTextExtent member function 
CDC class, 207 
GetTextFace member function 
CDC class, 208 
GetTextLen member function 
CListBox class, 366 
GetTextMetrics member function 
CDC class, 208 
Getting streams’ position, 904 
GetTopIndex member function 
CListBox class, 366 
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GetTopWindow member function 
CWhnd class, 700 

GetTotalSeconds member function 
CTimeSpan class, 624 

GetUpdateRect member function 
CWnd class, 700-701 

GetUpdateRgn member function 
CWnd class, 701 

GetUpperBound member function 
CObArray class, 456 

Get ViewportExt member function 
CDC class, 209 

GetViewportOrg member function 
CDC class, 209 

GetWindow member function 
CWnd class, 702 

GetWindowDC member function 
CWnd class, 703 

GetWindowExt member function 
CDC class, 209 

GetWindowOrg member function 
CDC class, 210 

GetWindowRect member function 
CWnd class, 703-704 

GetWindowText member function 
CWnd class, 704 

GetWindowTextLength member function 
CWnd class, 704-705 

Global functions 
AfxGetApp, 36 
AfxGetAppName, 36 
AfxGetInstanceHandle, 36 
AfxRegisterWndClass, 37 
diagnostic services, described, 43-57 
exception processing, 59, 67 
(list), 34—35 

Global variables 
afxMemDF, 46 

good member function 
10s Class, 859 

GotoDIgCtrl member function 
CDialog class, 268 

gptr member function 
streambuf class, 925 

Graphics Device Interface. See GDI. 

GRAYRECT structure 
CStatic::Create, 564 

GrayString member function 
CDC class, 210-212 


H 


Handlers 
message, 70-75 
WM_COMMAND messages, 69 
Handles 
CClientDC objects, 138 
GDI objects 
attaching, 344 
detaching, 347 
operating system file, 321 
retrieving to stock Windows GDI objects, 345-346 
returning to 
current instance of Windows application for 
accessing resources, 37 
current instance of Windows application, 36 
specifying to Windows menu, 419 
Windows applications 
current instance, 639 
previous instance, 639 
Windows GDI objects, attaching 
CGdiObject::FromHandle, 348 
CGdiObject::GetSafeHandle, 349 
CGdiObject::m_hObject, 351 
Windows, detaching from CWnd object, 676 
Height member function 
CRect class, 525 
HexDump member function 
CDumpContext class, 276 
HideCaret member function 
CWnd class, 705 
Hiding 
carets, 705 
CWhnd, called when, 783-784 
list box of combo box, 155 
scroll bars, 817-818 
Highlighting 
button control, 
getting, 132 
setting, 134 
top-level menu items, 705-706 
HiliteMenultem member function 
CWnd class, 705-706 
Hours 
getting minutes in current, 623 
getting total, 623 
getting, 613 
in current day, getting, 622 


1/O 
buffered disk file, filebuf class described, 831 
called before insert operations, 902 
clearing format flags, 864 
error testing, 857 
errors 
determining if error bits are set, 866 
returning current specified error state, 862 
testing for serious, 855 
testing if error bits are clear, 859 
extracting from streams, 880 
bytes, 883 
characters, 80 
data, 878, 880 
extraction operators, 885 
white space, 877 
filebuf class described, 831 
filebuf objects, 838 
fill character, setting, 869 
format flags 
clearing specified, 869 
setting, 870 
fstream class described, 836 
getting value of get pointer, 884 
insert operations, called after, 902 
1ostream class described, 872, 874 
fostream_init objects 
constructor, 874 
destructor, 874 
istream class described, 875 
masks, padding flag bits, 867 
obtaining 
floating-point format flag bits, 867 
radix flag bits, 867 
ofstream class described, 893 
ostream objects, 873 
ostream_withassign class described, 908 
ostrstream class described, 911 
putting extracted character back into stream, 882 
returning character without extracting, 882 
setting 
floating-point precision variable, 861 
internal field width variable, 865 
internal floating-point precision variable, 870 
specified format bits, 863 
stream’s mode to text, 871 
stdiobuf class described, 915 
stdiostr class described, 917 
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I/O (continued) 
stream buffers, returning number of bytes 
stored in, 913 
streambuf class described, 919 
streams 
assigning istream object to istream_withassign 
object, 889 
called after extraction operations, 881 
called prior to extraction operations, 880 
changing get pointer, 883 
synchronizing C++ with standard C stdio, 863 
synchronizing internal buffer with external 
character source, 884 
strstream class described, 939 
strstreambuf class described, 943 
testing for end of file, 857 
virtual overflow function, 926-927 
Icons 
activating and displaying, 800 
called if about to be dragged by user, 775 
called when background must be filled before 
painting, 743 
called when painting, 773 
called when user requests open window, 777 
drawing on CDC device, 176 
minimized document child windows, arranging, 406 
Identifying child windows, 709 
Idle state, called to inform main window, 737 
Idle-time processing, Windows applications, 637 
ifstream class 
described, 845 
member functions 
attach, 846 
close, 846 
fd, 847 
ifstream, 847-848 
~ifstream, 849 
is_open, 849 
open, 849-850 
rdbuf, 850 
setbuf, 850 
setmode, 851 
ifstream constructor, 847—848 
ifstream destructor, 849 
ifstream objects 
creating, 847-848 
destroying, 849 
ignore member function 
istream class, 880 
IMPLEMENT_DYNAMIC macro, 40, 471 
IMPLEMENT_SERIAL macro, 471 
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in_avail member function 
streambuf class, 926 
Inequality operator 
CRect class, 532 
InflateRect member function 
CRect class, 525-526 
Inflating rectangles, 525 
Information contexts, creating for specified 
device, 173 
InitApplication member function 
CWinApp class, 632 
InitApplication, CWinApp overridable member 
function, 11 
Initialization, Foundation classes vs. native 
Windows, 12 
Initializing 
menus, called when about to become active, 744 
modal dialog objects, 446-447 
Windows applications 
instance, 632 
one-time, 632 
InitInstance member function 
CWinApp class, 632 
InitInstance, overridable member function, 11 
In-memory files, CMemFile class described, 411 
Input 
sequential and random-access, istream class 
described, 875 
Input control, specifying for CWnd, 739-740 
Input focus 
called after gaining, 783 
called after window has realized logical palette, 
773-7174 
called before losing, 747-748 
called when ALT and another key pressed, 
791-792 
called when CWnd about to receive, 777 
called with release of key pressed with ALT, 
792-794 
claiming, 809 
specifying 
character value of dead key, 790-791 


virtual-key code of Control menu key, 786—787 


Insert operator, 593 
InsertAfter member function 
CObList class, 491-492 
InsertAt member function 
CObArray class, 456-457 
InsertBefore member function 
CObList class, 492—493 


Inserting 
arguments into streams, 906 
characters, into output stream, 903 
Clipboard data into edit control, 297 
element in array, 457 
new menu items, 428—430 
Insertion operator 
CArchive class, 103 
CDumpContext class, 278-279 
CString class, 593 
ostream class, 906 
InsertMenu member function 
CMenu class, 428—430 
CWnd::GetSystemMenu, 699 
InsertString member function 
CComboBox class, 151 
CListBox class, 366-367 
Integers, translating dialog box control 
text into, 690-691 
Internal character arrays 
returning pointer from stream, 914 
strstream class, returning pointer to, 940 
Internal field width variable, setting, 865 
Internal fill character variable, setting, 857 
IntersectClipRect member function 
CDC class, 212-213 
Intersection operator 
CRect class, 535 
IntersectRect member function 
CRect class, 526 
Invalidate member function 
CWnd class, 706-707 
InvalidateRect member function 
CWnd class, 707 
CEdit::SetTabStops, 302 
InvalidateRgn member function 
CWnd class, 708 
Invalidating 
client areas 
entire, 706—707 
within given rectangle, 707 
within given region, 708 
Inverting | 
rectangle contents, 213 
region colors, 214 
InvertRect member function 
CDC class, 213 
InvertRgn member function 
CDC class, 214 
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10S class 10s constructor, 860 
constructor, 860 10s destructor, 860 
data members 10S enumerators, 862 


adjustfield, 867 
basefield, 867 
floatfield, 867 
operator, 866 


described, 852—854 
manipulators 


los& binary, 868 
ios& dec, 868 
ios& hex, 868 
10Ss& oct, 869 
10s& text, 871 
resetiosflags, 869 
setfill, 869 
setiosflags, 870 
setprecision, 870 
setw, 871 


member functions 


bad, 855 
bitalloc, 855 
clear, 856 
delbuf, 856—857 
eof, 857 

fail, 857 

fill, 857—858 
flags, 858-859 
good, 859 
hex, 855 

in, 930 

108, 860 

~i0s, 860 
iword, 860 
left, 855 

out, 930 
precision, 861 
pword, 861 
rdbuf, 862 
rdstate, 862 
setf, 863 

stdio, 863, 902 
sync_with_stdio, 863 
tie, 864 
unitbuf, 902 
unsetf, 864 
width, 865 
xalloc, 865 


operators, 867 
virtual destructor, 860 


1ostream class 
described, 872-873 
member functions 
10stream, 873 
~iostream, 873 
iostream constructor, 873 
iostream destructor, 873 
iostream objects, 873 
lostream_init class 
described, 874 
member functions 
Iostream_init, 874 
~lostream_init, 874 
Iostream_init constructor, 874 
Iostream_init destructor, 874 
ipfx member function 
istream class, 880-881 
IsChild member function 
CWnd class, 709 
IsDialogMessage member function 
CDialog class, 268-269 
IsDlgButtonChecked member function 
CWnd class, 709 
IsEmpty member function 
CMapStringToOb class, 382 
CObList class, 493 
CString class, 584-585 
isfx member function 
istream class, 881 
IsIconic member function 
CWnd class, 710 
IsKindOf member function 
CObject class, 472 
CArchive::ReadObject, 100 
IsLoading member function 
CArchive class, 98 
CObject::Serialize, 473 
is_open member function 
filebuf class, 834 
fstream class, 842 
ifstream class, 849 
ofstream class, 895 
IsRectEmpty member function 
CRect class, 527 
IsRectNull member function 
CRect class, 527 
IsSerializable member function 
CObject class, 473 
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IsStoring member function 
CArchive class, 98 
CObject::Serialize, 473 

istream class 
described, 875-876, 887 
extraction operators, 885 
manipulator, 886 
member functions 

eatwhite, 877 
gcount, 877 
get, 878-879 
getline, 879-880 
ignore, 880 
ipfx, 880-88 1 
isfx, 881 
istream, 881 
~istream, 882 
peek, 882 
putback, 882 
read, 882-883 
seekg, 883 
sync, 884 
tellg, 884 
operators, 885, 889 

istream constructor, 881 

istream destructor, 882, 888-889 

istream objects 
assigning to istream_withassign object, 889 
creating, 881 
destroying, 882 

istream_withassign class 
described, 887 
member functions 

istream_withassign, 888 
~istream_withassign, 888 

istream_withassign constructor, 888 

istream_withassign destructor, 888 

istream_withassign objects 
creating, 888 
destroying, 888 

istrstream class 
described, 890 
member functions 

istrstream, 891 
~istrstream, 891 
rdbuf, 892 
str, 892 
istrstream constructor, 891 
istrstream destructor, 891 


istrstream objects 
creating, 891 
destroying, 891 
IsWindowEnabled member function 
CWhnd class, 710 
IsWindow Visible member function 
CWnd class, 710 
IsZoomed member function 
CWnd class, 711 
iword member function 
i0s class, 860 


J 


Justification, text, setting, 248-249 


K 


Key lookups, 27 
Keyboard 
input 
enabling or disabling, 681 
retuming active key, 718-719 


specifying whether CWnd is enabled for, 710 


Keys, nonsystem 
called on input, 745—746 
called on release, 746-747 
KillTimer member function 
CWnd class, 711 


L 


Left member function 
CString class, 585 
108 class 
i0s::bitalloc, 855 
Length 
files 
changing, 318 
getting in bytes, 309 
LimitText member function 
CComboBox class, 152 
CEdit class, 294 
Line, numbers, retrieving from multiple-line edit 
control, 29 1—292 
LineFromChar member function 
CEdit class, 294 
LineIndex member function 
CEdit class, 295 
LineLength member function 
CEdit class, 295-296 


Lines 
drawing from current position, 214 
length in edit control, 295 
numbers, retrieving from edit control, 294 
LineScroll member function 
CEdit class, 296 
LineTo member function 
CDC class, 214 
List boxes 
adding filenames to, 360 
called when control created, 754-756 
called with keyboard input, 795-796 
CListbox class described, 352 
comparing items in, 722-724 
creating 
constructor, 355 
specifying style, 356-359 
describing deleted item, 80 
destroying, 729-730 
filling with directory listing, 676-677 
finding specified string, 361 
getting string from, 365 
items 
deleting, 359 
ensuring visibility, 372 
removing, 367 
retrieves zero-based index of currently selected, 362 
retrieving index of first visible, 363 
retrieving index of first visible, 366 
retrieving number of, 361 
retrieving selection state, 364 
searching for match to string, 367 
selecting consecutive, 368 
setting associated 32-bit values, 370 
total selected, 364 
multicolumn, selecting width, 369 
multiple-selection, selecting strings in, 371 
of combo boxes 
retrieving current selection, 680-68 1 
returning selected items, 149 
retrieving 
bounding rectangle dimensions, 363 
current selection, 679-680 
horizontal scrolling event, 362 
returning on application response, 719-720 
scrolling 
selected strings, 369 
setting width, 370 
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List boxes (continued) 


strings 
adding, 355 
getting length, 366 
getting, 365 
inserting, 366 


supplying identifiers for two items in, 77—78 
List classes, 27 
Lists 


adding element or list to tail, 480-481 
classes described, 27 

COblist class described, 477 

CPtrList class described, 519 
creating, 482-483 
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CString objects, CStringList class described, 603 


elements, 486-487 

adding after specified position, 491 

adding before specified position, 492 

getting number of, 485 

head, getting position, 487 

indicating if empty, 493 

next, getting position, 488 

previous, getting position, 489 

removing all, 493 

removing head, 495 

removing specified, 494 

removing tail, 496 

scanning index for, 484 

tail, getting position, 491 

tail, getting, 490 

writing pointer to specified position, 496 
retrieving pointer to given position, 485 
scanning index for specified element, 484 


searching for first matching CObject pointer, 483 


LoadAccelTable member function 


CFrameWnd class, 340 


LoadBitmap member function 


CBitmap class, 114 
CBrush::CreatePatternBrush, 123 
CWnd::CreateCaret, 665 


LoadCursor member function 


CWinApp class, 633 
CWnd::OnQueryDragIcon, 775 


LoadIcon member function 


CWinApp class, 633-634 
CDC::DrawlIcon, 176 
CWnd::OnQuery DragIcon, 775 


992 Index 


Loading M 
accelerator tables, 340 
bitmap resources, 114 m_cause data member 
menu resources, 430 CArchiveException class, 106 
object or primitive type from archive, 102 CFileException class, 327-328 
predefined cursor resources CFileException::ErrnoToException, 324 
CWinApp::LoadStandardCursor, 635 m_hAccelTable data member 
CWinApp::LoadOEMCursor, 634 CFrameWnd class, 341 
icon resource, predefined, 633, 634, 536 m_hFile data member 
specified cursor resource, 633 CFile class, 321 
LoadMenu member function m_hInstance data member 
CMenu class, 430 CWinApp class, 639 
LoadMenulIndirect member function m_hObject data member 
CMenu class, 431 CGdiObject class, 351 
LoadOEMBitmap member function m_hPrevInstance data member 
CBitmap class, 115-116 CWinApp class, 639 
LoadOEMCursor member function m_hWnd data member 
CWinApp class, 634 CClientDC class, 138 
LoadOEMIcon member function CPaintDC class, 500 
CWinApp class, 634-635 CWindowDC class, 643 
CDC::DrawlIcon, 176 CWnd class, 822 
LoadStandardCursor member function m_hWndMD!IClient data member 
CWinApp class, 635-636 CMDIFrameWnd class, 410 
LoadStandardIcon member function m_lOsError data member 
CWinApp class, 636—637 CFileException class, 328 
CDC::Drawlcon, 176 m_IpCmdLine data member 
LoadString member function CWinApp class, 639 
CString class, 585-586 m_msgCur data member 
Locking CWinApp class, 639 
range of bytes in open file, 312 m_nCmdShow data member 
LockRange member function CWinApp class, 640 
CFile class, 312-313 CWnd::Show Window, 819 
Logical palettes. See Palettes m_pMainWnd data member 
Lookup member function CWinApp class, 640 
CMapStringToOb class, 382 m_pMDIFrameWnd data member 
LPRECT operator CMD!IChildWnd class, 400 
CRect class, 531 m_ps data member 
LPRECT structure CPaintDC class, 500 
CDC::Arc, 166 m_pStream data member 
CDC::Chord, 171 CStdioFile class, 571 
CRect::CRect, 524 m_pszAppName data member 
CRect::operatorLPRECT, 531 CWinApp class, 640 
LPtoDP member function Macros 
CDC class, 215 AND_CATCH, 65 


ASSERT, 53 


Macros (continued) 
ASSERT_VALID, 53 
DEBUG_NEW, 38 
DECLARE _ DYNAMIC, 38-39, 468 
DECLARE_SERIAL, 39-40, 468 
diagnostic services, described, 49-52, 55, 57 
END_CATCH, 66 
exception processing, 59, 67 
exception-handling, 30 
IMPLEMENT_DYNAMIC, 471 
IMPLEMENT_SERIAL, 471 
(list), 32-33 
RUNTIME_CLASS, 474 
THROW, 66 
THROW_LAST, 67 
TRACE, 56 
TRY, 67 
VERIFY, 57 

Main application class, CWinApp 
described, 11 

MakeLower member function 
CString class, 586 

MakeReverse member function 
CString class, 586 

MakeUpper member function 
CString class, 587 

Manipulators 
ios class, 868-871 
istream class, 886 
ostream class, 907 

MapDialogRect member function 
CDialog class, 270 

Mapping 
device contexts, logical palettes to system 

palettes, 224 

fonts, logical to physical, 241 
mode, retrieving current, 201 
point coordinates, 175 
setting mode, 240-241 

Maps 
16-bit words keyed to void pointers, 375 
classes described, 27 
CMapPtrToPtr class described, 373 
CMapPtrToWord class described, 375 
CMapStringToOb class described, 377 
CMapStringToPt class described, 387 
CMapStringToString class described, 389 
CMapWordToOb class described, 391 
CMapWordToPtr class described, 393 
CObject pointers keyed by 16-bit words, 391 
constructing CString-to-CObject, 379 
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Maps (continued) 
CString objects keyed to CString objects, 389 
CString objects to CObject pointers, 377 
defined, 27 
finding element with matching key, 382 
getting number of elements, 380 
inserting elements 
CMapStringToOb::operator[], 386 
CMapStringToOb::SetAt, 384 
interation, starting, 381 
iterating through all elements, 380-38 1 
looking up entry corresponding to supplied 
key, 83-384 
message cross-reference, 69 
message, defined, 13 
removing elements and destroying CString key 
objects, 383 
testing if empty, 382 
to void pointers keyed by void pointers, 373 
void pointers 
keyed by 16-bit words, 393 
keyed by CString objects, 387 
Masks 
current radix flag bits, 867 
floating-point format flag bits, 867 
padding flag bits, 867 
Maximization, CWnd, determining, 711 
Maximizing MDI child windows, 399 
MDI 
client window handle, 410 
client windows, arranging in cascade, 406 
window, child, activating, 405 
MDtIActivate member function 
CMDIChildWnd class, 398 
CMDIFrameWnd class, 405 
CWnd::OnMDtIActivate, 754 
MDICascade member function 
CMDIFrameWnd class, 406 
MD IDestroy member function 
CMDIChildWnd class, 399 
MDIGetActive member function 
CMDIFrameWnd class, 406 
MDIIconArrange member function 
CMDIFrameWnd class, 406 
CWnd::ArrangeIconicWindows, 659 
MDIMaximize member function 
CMD!IChildWnd class, 399 
CMDIFrameWnd class, 407 
MDINext member function 
CMDIFrameWnd class, 407 
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MDIRestore member function 
CMDIChildWnd class, 399 
CMDIFrameWnd class, 408 

MDISetMenu member function 
CMDIFrameWnd class, 408—409 

MDITile member function 
CMDIFrameWnd class, 409 


MEASUREITEMSTRUCT structure, 83—84 


CWnd::OnMeasureltem, 754—755 
Member functions 
CArchive class, 95-101 
CArchiveException class, 105 
CBitmap class, 109-117 
CBrush class, 119-125 
CButton class, 128-134 
CClientDC class, 138 
CComboBox class, 142—155 
CDC class, 164—260 
CDialog class, 264—272 
CDumpContext class, 275-277 
CEdit class, 285—302 
CFile class, 306—320 
CFileException class, 324-326 
CFrameWnd class, 338-340 
CGdiObject class, 344-350 
CListBox class, 355—372 
CMapStringToOb class, 379-385 
CMDIChildWnd class, 397—399 
CMDIFrameWnd class, 403—409 
CMemFile class, 412 
CMemoryException class, 413 
CMenu class, 416-437 
CMetaFileDC class, 440-442 
CModalDialog class, 446-448 


CNotSupportedException class, 449 


CObArray class, 453-462 
CObject class, 466-476 
CObList class, 480-497 
CPaintDC class, 499-500 
CPalette class, 503—507 
CPen class, 509-511 
CPoint class, 513-516 
CRect class, 523—530 
CResourceException class, 536 
CRen class, 539-550 
CScrollBar class, 553—557 
CSize class, 559 

CStatic class, 563-566 
CStdioFile class, 568—570 
CString class, 576-591 
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CTime class, 608 
CTimeSpan class, 620-624 
CWindowDC class, 642 
CWinApp class, 631-638 
CWnd class, 659-821 
filebuf class, 832—835 
fstream class, 838-844 
ifstream class, 846-85 1 

i0s class, 855—865 

iostream class, 873 
Iostream_init class, 874 
istream class, 877-889 
istream_withassign class, 888 
istrstream class, 891-892 
ofstream class, 894-899 
ostream class, 902—909 
ostream_withassign class, 909 
ostrstream class, 912-914 
stdiostream class, 918 
stdiobuf class, 916 
stdiostream class, 918 
streambuf class, 922—938 
strstream class, 940-942 
strstreambuf class, 944-946 


Memory 


compaction, specifying time currently spent in, 722 
corrupted, matching with contents, 55 
diagnostics described, 29 
exceptions, CMemoryException objects, 413 
files 

closing, 412 

opening, 412 
finding leaks, 38 
handles, retrieving for multiple-line edit 

control, 291 

in-memory files, CMemFile class described, 411 
leaks, testing CObject objects, 598 
low, detecting, 722 
taking snapshot, 54 
testing address, 50 


Memory allocation 


arrays, freeing extra memory, 455 
checking for corrupt guard bytes, 47 
CObject class, optimizing allocation, 475 
debugging 
forcing program halt on specified sequence 
numbers, 52 
tuning allocation diagnostics, 46 
freeing memory, 475 


Memory allocation (continued) 


memory files 
closing, 412 
opening, 412 
multiple-line edit control, handles, retrieving, 291 
preventing memory deletion for strstreambuf object 
with dynamic array, 944 
setting 
handle to local memory, 297 
hook, 51 
testing to ensure memory blocks are contained in 
program’s memory space, 51 


Menu bars, redrawing, 681 
Menus 


bars, redrawing, 681 
called when about to become active, 744 
calling owner when menu changes, 732-735 
CMenu class described, 414 
Control 
allowing application access, 699 
called when Maximize or Minimize button 
selected, 788—790 
called when item selected, 721 
creating 
empty, 421 
pop-up, 421 
CWnd 
retrieving pointer to, 693 
deleting items, 422 
destroying 
CMenu::~CMenu, 421 
specified, CMenu::DestroyMenu, 423 
detaching from, CMenu object, 423 
highlighting, activating or removing from top-level 
items, 705—706 
items 
adding, 428-430 
appending new, 416-418 
associating bitmaps with, 435-436 
called when user selects, 757—758 
changing, 432-433 
copying label to, 427 
determining number, 424 
enabling, 423-424 
removing, 434 
specifying items to be checked, 419-420 
specifying position of active, 425 
specifying status, 425-426 
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Menus (continued) 
MDI, replacing menu of, 408-409 
mnemonic character, called when user presses, 
756-757 
pop-up 
called when about to become active, 744-745 
check mark control, 419-420 
creating, 421 
determining number of items, 424 
displaying floating, 436-437 
replacing, 408-409 
retrieving CMenu object, 428 
resources, loading and attaching to CMenu 
object, 430 
loading from menu template and attaching to 
CMenu object, 431 
setting current to specified, 810 
template, loading resource and attaching to CMenu 
object, 431 
Windows, specifying handle to, 419 
Message boxes, called when about to be 
drawn, 726—727 
Message maps 
cross-reference, 69 
function categories, 70 
Message processing, Foundation classes vs. native 
Windows, 9 
MessageBox member function 
CWnd class, 711-714 
Messages 
applications, creating and displaying, 711-714 
boxes, called with displaying, 717 
called when CWnd first created, 762—763 
calling default window procedure 
CWnd::Default, 673 
CWnd::DefWindowProc, 674 
control, 14 
cross-reference map, 69 
CWnd, placing message in queue, 800 
determining whether intended for modeless dialog 
box, 268-269 
direct calls to Windows, 16 
handlers, 70-75 
idle-time processing, 637 
map defined, 13 
notification, 13—14 
providing Windows procedure for, 821 
returning pointer to current, 688 
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Messages (continued) 
sending to specified control, 804 
sending to window, 805 
used to translate CWinApp window messages, 801 
Windows applications 
filtering, 638 
providing default loop, 638 
Messaging, Windows, 8 
Metafiles 
closing device context and creating handle to 
play, 440 
CMetafileCD class described, 438 
playing on given device, 221 
selecting object into CMetaFileDC, 441 
selecting predefined stock of pens, brushes, 
fonts, 442 
Mid member function 
CString class, 587-588 
Minimizing CWnd, 664 
Minutes 
getting total, 624 
getting, 613 
in current hour, getting, 623 
Modification flag, setting for edit control, 298 
Modifying 
menu items, 432—433 
viewport extents, 228 
window extents, 229 
ModifyMenu member function 
CMenu class, 432-433 
CWnd::GetSystemMenu, 699 
Months, getting, 613 
Mouse 
capture 
called by CWnd, 763-764 
retrieving CWnd, 685 
cursor 
called on press of button, 758-759 
called when input isn’t captured, 782 
called when moved, 760 
enumerated values (list), 88 
input 


causing all subsequent to be sent to current CWnd 


object, 806 
enabling or disabling, 681-682 
specifying whether CWnd is enabled for, 710 
Mouse button 
called when clicked over child window, 774—775 
tracking pop-up menu item selection, 436-437 


Mouse button, left 
called when double-clicked in nonclient 
area, 765, 767 
called when double-clicked, 748-749 
called when pressed in nonclient area, 765-766 
called when pressed, 749 
called when released, 750 
Mouse button, middle 
called when double-clicked, 751 
called when pressed in nonclient area, 767—768 
called when pressed, 752 
called when released in nonclient area, 768 
called when released, 752—753 
Mouse button, right 
called when double-clicked within nonclient 
area, 770 
called when double-clicked, 778 


called when pressed within nonclient area, 770-771 


called when pressed, 779 
called when released within nonclient area, 771 
called when released, 780 
MoveTo member function 
CDC class, 215-216 
MoveWindow member function 
CWnd class, 714-715 
Moving 
clipping region, 216 
current point position, 215 
CWnd, called when, 760—761 
rectangles, 527, 533 
regions, 547 
MS-DOS, device names, conventions, 174 
Multiple document interface. See MDI 
Multiple-line edit control 
character index, retrieving line number, 294 
character line index, retrieving, 295 
formatting rectangle 
setting, 299 
setting new dimensions, 300 
line numbers, retrieving, 291-292 
number of lines, retrieving, 292 
retrieving local memory handle, 291 
scrolling text, 296 
setting 
handle to local memory, 297 
tab stops, 301 
soft line-break characters, inserting, 290 


new operator 
CObject class, 475 
NextDlgCtrl member function 
CDialog class, 270 
Nonclient areas 
calculating size, 762 
called when destroyed, 763 
called when mouse button pressed in, 765—766 
called when needing painting, 769 
Nonsystem key 
called when pressed, 745-746 
called when released, 746—747 


0 


Object diagnostics 
class-oriented, 24 
described, 24 
dump context, 24 
validity checking, 25 
Object persistence described, 23 
Objects 
CObject class described, 463 
creating, 467 
destroying, 467 
dumping to CObject objects, 469-470 
getting run-time structure, 470 
reading or writing to archive, 473-474 
testing 
for class, 472 
if eligible for serialization, 473 
validity checking, 466 
OEM, converting characters to ANSI character 
set, 588 
OemToAnsi member function 
CString class, 588 
Offset member function 
CPoint class, 514 
OffsetClipRgn member function 
CDC class, 216 
OffsetRect member function 
CRect class, 527-528 
OffsetRgn member function 
CRgn class, 547-548 
OffsetViewportOrg member function 
CDC class, 217 
OffsetWindowOrg member function 
CDC class, 217 
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ofstream class 
described, 893 
member functions 
attach, 894 
close, 894 
fd, 895 
is_open, 895 
ofstream, 895—897 
~ofstream, 897 
open, 898 
rdbuf, 898 
setbuf, 899 
setmode, 899 
ofstream constructor, 895-897 
ofstream destructor, 897 
ofstream objects 
creating, 896-897 
destroying, 841, 897 
OK button, overriding in dialog boxes, 448 
OnActivate member function 
CWnd class, 715 
OnActivateApp member function 
CWhnd class, 716 
OnAskCbFormatName member function 
CWnd class, 716-717 
OnCancel member function 
CModalDialog class, 448 
OnCancelMode member function 
CWnd class, 717 
OnChangeCbChain member function 
CWnd class, 717-718 
OnChar member function 
CWnd class, 718-719 
OnCharToltem member function 
CWnd class, 719-720 
OnChildActivate member function 
CWnd class, 720 
OnClose member function 
CWnd class, 720 
OnCommand member function 
CWnd class, 721 
OnCompacting member function 
CWnd class, 722 
OnComparelItem member function 
CWnd class, 722—724 
OnCreate member function 
CWnd class, 724—726 
OnCtlColor member function 
CWnd class, 726-727 
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OnDeadChar member function 
CWnd class, 727-729 
OnDeleteItem member function 
CWhnd class, 729-730 
OnDestroy member function 
CWnd class, 730 
OnDestroyClipboard member function 
CWnd class, 731 
OnDevModeChange member function 
CWnd class, 731 
OnDrawClipboard member function 
CWnd class, 731-732 
OnDrawlItem member function 
CWnd class, 732-735 
OnEnable member function 
CWnd class, 735-736 
OnEndSession member function 
CWnd class, 736 
OnEnterIdle member function 
CWhnd class, 737 
OnEraseBkgnd member function 
CWhnd class, 737-738 
OnFontChange member function 
CWnd class, 738-739 
OnGetDlgCode member function 
CWnd class, 739-740 
OnGetMinMaxInfo member function 
CWhnd class, 740-741 
OnHScroll member function 
CWhnd class, 741-742 
OnHScrollClipboard member function 
CWnd class, 742-743 
OnlIconEraseBkgnd member function 
CWhnd class, 743 
OnlIdle member function 
CWinApp class, 637 
overridable member function, 11 
OnInitDialog member function 
CDialog class, 271 
OnInitMenu member function 
CWhnd class, 744 
OnInitMenuPopup member function 
CWnd class, 744—745 
OnKeyDown member function 
CWnd class, 745—746 
OnKeyUp member function 
CWhnd class, 746—747 
OnKillFocus member function 
CWnd class, 747-748 
OnLButtonDbIClk member function 
CWnd class, 748-749 


OnLButtonDown member function 
CWnd class, 749 

OnLButtonUp member function 
CWhd class, 750 

OnMButtonDbIClk member function 
CWnd class, 751 

OnMButtonDown member function 
CWnd class, 752 

OnMButtonUp member function 
CWnd class, 752-753 

OnMDIActivate member function 
CWnd class, 753-754 

OnMeasureltem member function 
CWnd class, 754—756 

OnMenuChar member function 
CWnd class, 756-757 

OnMenuSelect member function 
CWnd class, 757-758 

OnMouseActivate member function 
CWnd class, 758—759 

OnMouseMove member function 
CWnd class, 760 

OnMove member function 
CWnd class, 760-761 

OnNcActivate member function 
CWnd class, 761 

OnNcCalcSize member function 
CWnd class, 762 

OnNcCreate member function 
CWnd class, 762—763 

OnNcDestroy member function 
CWnd class, 763 

OnNcHitTest member function 
CWnd class, 763-764 

OnNcLButtonDbIClk member function 
CWnd class, 765 

OnNcLButtonDown member function 
CWhnd class, 765—766 

OnNcLButtonUp member function 
CWnd class, 766 

OnNcMButtonDbIClk member function 
CWnd class, 767 

OnNcMButtonDown member function 
CWnd class, 767—768 

OnNcMButtonUp member function 
CWnd class, 768 

OnNcMouseMove member function 
CWnd class, 769 

OnNcPaint member function 
CWnd class, 769 


OnNcRButtonDbIClk member function 
CWnd class, 770 
OnNcRButtonDown member function 
CWnd class, 770-771 
OnNcRButtonUp member function 
CWnd class, 771 
OnOK member function 
CModalDialog class, 448 
OnPaint member function 
CWnd class, 772 
OnPaintClipboard member function 
CWnd class, 772—773 
OnPaintIcon member function 
CWnd class, 773 
OnPaletteChanged member function 
CWnd class, 773-774 
OnParentNotify member function 
CWnd class, 774—775 
OnQueryDragIcon member function 
CWnd class, 775—776 
OnQueryEndSession member function 
CWnd class, 776 
OnQueryNewPalette member function 
CWnd class, 777 
OnQueryOpen member function 
CWnd class, 777 
OnRButtonDbIClk member function 
CWnd class, 778 
OnRButtonDown member function 
CWnd class, 779 
OnRButtonUp member function 
CWnd class, 780 
OnRenderAllFormats member function 
CWnd class, 780-78 | 
OnRenderFormat member function 
CWhnd class, 781 
OnSetCursor member function 
CWnd class, 782 
OnSetFocus member function 
CWnd class, 783 
OnSetFont member function 
CDialog class, 271-272 
OnShow Window member function 
CWnd class, 783-784 
OnSize member function 
CWnd class, 784—785 
OnSizeClipboard member function 
CWnd class, 785 
OnSpoolerStatus member function 
CWnd class, 786 
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OnSysChar member function 
CWnd class, 786—787 
OnSysColorChange member function 
CWnd class, 788 
OnSysCommand member function 
CWnd class, 788-790 
OnSysDeadChar member function 
CWnd class, 790-791 
OnSysKeyDown member function 
CWnd class, 791-792 
OnSysKeyUp member function 
CWnd class, 792-794 
OnTimeChange member function 
CWnd class, 794 
OnTimer member function 
CWnd class, 795 
OnVKeyToltem member function 
CWnd class, 795—796 
OnVScroll member function 
CWnd class, 796-797 
OnVScrollClipboard member function 
CWnd class, 797-798 
OnWinIniChange member function 
CWnd class, 798-799 
Open member function 
CFile class, 313-314 
open member function 
filebuf class, 834-835 
fstream class, 842 
ifstream class, 849-850 
ofstream class, 898 
OpenClipboard member function 
CWnd class, 799 
OpenIcon member function 
CWhnd class, 800 
Opening 
Clipboard, 799 
files 
CFile::Open, 313 


for attachment to stream’s filebuf object, 842 
for attachment to stream’s filebuf object, 849 


for attachment to stream’s filebuf, 898 


for connection to filebuf objects, 834-835 


memory, 412 
Operating system 
error codes 
CFileException::CFileException, 324 
CFileException::m_lOsError, 328 


CFileException::OsErrorToException, 325 


CFileException::ThrowOsError, 326 
handle for open file, 321 
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Operators Operators (continued) 
addition operator subscript operator 
CRect class, 534 CString class, 597 
_ CString class, 594 subtraction operator 
CTime class, 615-616 CRect class, 533-534 
CTimeSpan class, 625 union operator 
assignment of addition operator CRect class, 531, 535 
CRect class, 532 void* operator 
CString class, 595 10s class, 867 
CTime class, 616 opfx member function 
CTimeSpan class, 626 ostream class, 902 
assignment of intersection operator OsErrorToException data member 
CRect class, 533 CFileException class, 325 
assignment of subtraction operator osfx member function 
CRect class, 533 ostream class, 902 
assignment of union operator ostream, tying stream to, 10s::tie, 864 
CRect class, 533-534 ostream class 
assignment operator described, 900-901, 908 
CRect class, 531 manipulators 
CSize class, 560—561 &endl, 907 
CString class, 592 &ends, 907 
CTime class, 615 &flush, 907 
CTimeSpan class, 625 member functions 
istream class, 889 flush, 902 
ostream class, 910 opfx, 902 
const char *() operator osfx, 902 
CString class, 592-593 ostream, 903 
equality operator ~ostream, 903 
CRect class, 531 put, 903 
extraction seekp, 904 
CArchive class, 102 tellp, 904-905 
CString class, 593 write, 905 
CTime class, 617 operators, 906, 910 
CTimeSpan class, 627 ostream constructor, 903 
istream class, 885 ostream destructor, 903, 909 
inequality operator, CRect class, 532 ostream objects 
insertion assigning to ostream_withassign object, 910 
CArchive class, 103 ostream_withassign class 
CDumpContext class, 278-279 described, 908 
ostream class, 906 member functions 
intersection operator ostream_withassign, 909 
CRect class, 535 ~ostream_withassign, 909 
lookup operator operator, 910 
CMapStringtoOb class, 386 ostream_withassign constructor, 908 
LPRECT operator ostream_withassign destructor, 908 
CRect class, 531 ostream_withassign objects 
new operator assigning specified ostream object to, 910 
CObject class, 475 creating, 909 


destroying, 909 


ostrstream class 
described, 911 
member functions 
ostrstream, 912 
~ostrstream, 913 
pcount, 913 
rdbuf, 913 
str, 914 
returning pointer to internal character array, 914 
ostrstream constructor, 912 
ostrstream destructor, 913 
ostrstream objects 
creating, 912 
destroying, 913 
Output 
diagnostic, 29 
sequential and random-access, ostream class 
described, 900 
out_waiting member function 
streambuf class, 926 
overflow member function 
streambuf class, 926—927 


p 
Painting 
called to prepare invalidated region, 737—738 
called when repainting CWnd, 772 
client area associated with CPaintDC object, 500 
client area of window, 84-85 
CPaintDC class described, 498 
CWnd, called when client area needs 
repainting, 772-773 
icon background, 743 
icons, called when painting, 773 
nonclient areas, called when needing, 769 
preparing CWnd for, 660 
windows, marking end, 682 
PaintRgn member function 
CDC class, 218 
PAINTSTRUCT structure, 84-85 
CPaintDC::CPaintDC, 499 
CPaintDC::m_ps, 500 
CWnd::BeginPaint, 660 
CWnd::EndPaint, 682 
CWnd::OnPaintClipboard, 772-773 
Palettes 
CPalette class described, 501 
creating CPalette objects, 504 
CWnd, called when receiving input focus, 777 
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Palettes (continued) 
logical 
mapping entries to system palette, 224 
replacing entries, 503 
retrieving closest matching entry, 505 
retrieving range of entries, 505 
setting RGB color values and flags, 506 
resetting, 350 
resizing, 506 
returning pointer to CPalette object, 504 
selecting logical, 233 
system, called after change, 773-774 
Parent windows 
called when child window created or 
destroyed, 774—775 
changing parent of child, 810 
retrieving, 696 
Password character, setting or removing in edit 
control, 299 
Paste member function 
CComboBox class, 152 
CEdit class, 297 
Pasting Clipboard data into edit control, 297 
PatBlt member function 
CDC class, 218-219 
pbackfail member function 
streambuf class, 927 
pbase member function 
streambuf class, 928 
pbump member function 
streambuf class, 928 
pcount member function 
ostrstream class, 913 
strstream class, 940 
peek member function 
istream class, 882 
Pens 
available in device context, enumerating, 182-184 
CPen class described, 508 
creating 
constructor, 509 
initializing 510 
initializing with specified structure, 510 
handles, 511 
predefined 
retrieving handle to, 345-346 
selecting, 442 
setting drawing mode, 243-244 
Pie member function 
CDC class, 219-220 
Pie-shaped wedges, creating, 219-220 
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Pixels Pointers (continued) 
retrieving RGB color values, 202 CObject 
setting at specified point, 242 lists, COblist class described, 477 
PlayMetaFile member function maps to CString objects, 377 
CDC class, 221 ~ CWnd 
CMetaFileDC::Close, 440 . object when given handle to window, 684 
POINT structure, 85 retrieving to active, 685 
CDC::Arc, 166 | get 
CDC::Chord, 171 advancing past spaces and tabs, 877 
CDC::DPtoLP, 175 changing for stream, 883 
CDC::Drawlcon, 176 getting value, 884 
CDC::GetPixel, 202 incrementing, 925 
CDC::LineTo, 214 put, incrementing, 928 
CDC::LPtoDP, 215 repositioning external file pointer, 927 
CDC::MoveTo, 215 returning, display context for client area, 688 
CDC::Pie, 220 void 
CDC::Polygon, 221 16-bit words keyed by, 375 
CDC::PolyPolygon, 222 CPtrArray class described, 517 
CDC::PtVisible, 223 CPtrList class described, 519 
CDC::RoundRect, 227 keyed by void pointers, 373 
CDC::SetBrushOrg, 239 maps keyed by 16-bit words, 393 
CDC::SetPixel, 242 maps keyed by CString objects, 387 
CDC::SetViewportOrg, 251 Pointers, file. See File pointers 
CDC::SetWindowOrg, 253 Points 
CDialog::IsDialogMessage, 269 adding separate values to x and y members, 513 
CPen::CreatePenIndirect, 511 checking 
CPoint::CPoint, 513 equality between two, 515 
CPoint::Offset, 514 if within region, 548 
CPoint::operator, 515-516 inequality between two, 515 
CRect::BottomRight, 523 converting, logical to device, 215 
CRect::OffsetRect, 528 CPoint class described, 512 
CRect::operator +, 534 defining x- and y-coordinates of, 85 
CRect::operator +=, 532 determining if within rectangles, 528 
CRect::operator —, 534 identifying window containing given, 821 
CRect::operator — =, 533 mapping coordinates from device to logical 
CRect::PtInRect, 528 system, 175 
CRegn::CreatePolygonRegn, 542 offsetting by a size, 515-516 
CRgn::CreatePolyPolygonRgn, 543 offsetting negatively by a size, 516 
CRegn::OffsetRgn, 547 rectangles 
CRegn::PtInRegion, 548 referencing bottom right, 523 
CSize::CSize, 559 referencing top left, 529 
CWnd::ClientToScreen, 663 specified, determining which child window 
CWnd::OnGetMinMaxInfo, 740 : contains, 662—663 
CWnd::ScreenToClient, 802 subtracting a size, 516 
CWnd:: WindowFromPoint, 821 Polygon member function 
Pointers CDC class, 221 
arrays, removing all from, 458 Polygons 
CFile object, getting for archive, 97 creating multiple filled, 222 
CMDIChildWnd to parent CMDIFrameWnd, 400 drawing, 221 


filling mode, retrieving current, 203 


Polygons (continued) 
regions 
creating series of, 543 
creating, 542 
setting, filling mode, 242 
Polyline member function 
CDC class, 222 
Polymorphism among Foundation classes, 10 
PolyPolygon member function 
CDC class, 222—223 
Pop-up menus 
called when about to become active, 744—745 
determining number of items, 424 
displaying floating, with item tracking, 436-437 
obtaining item identifier, 425 
retrieving CMenu object, 428 
specifying status of items, 425-426 
Pop-up windows, determining most recently 
active, 692-693 
Position, retrieving current, 195 
PostMessage member function 
CWnd class, 800-801 
pptr member function 
streambuf class, 928 
precision member function 
ios Class, 861 
Predefined stream objects 
cerr, 900 
cin, 875 
clog, 900 
cout, 900 
PreTranslateMessage member function 
CWinApp class, 638 
CWnd class, 801 
PrevDlgCtrl member function 
CDialog class, 272 
Printing 
aborting current job, 164 
ending 
job, 80 
page, 181 
informing device driver of new job, 254 
installing abort procedure in job, 235—237 
job, called when adding or deleting from queue, 786 
memory Statistics report, 56 
preparing printer driver to receive data, 254 
Private assignment operator, 475 
PtInRect member function 
CRect class, 528 
PtInRegion member function 
CRgn class, 548 
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PtVisible member function 
CDC class, 223 
Pushbutton control, dialog boxes 
changing default, 272 
getting default ID, 268 
put areas 
returning 
first byte of, , 928 
number of characters available for fetching, 926 
pointer to byte after last, 925 
pointer to start of, 928 
setting pointer values, 932 
storing character, 934 
put member function 
ostream class, 903 
Put pointers 
following stored characters, 935 
incrementing, 928 
putback member function 
istream class, 882 
pword member function 
10s class, 861 


R 


Radio buttons 
check-marking, 662 
CWnd, retrieving ID of check-marked, 686 
getting check state, 132 
setting 
check state, 134 
highlighting control, 132 
Raster operations, 172 
Raster-operation codes (list), 167-168 
rdbuf member function 
fstream class, 843 
ifstream class, 850 
10S Class, 862 
istrstream class, 892 
ofstream class, 898 
ostrstream class, 913 
stdiostream class, 918 
strstream class, 940 
rdstate member function 
10S class, 862 
Read member function 
CArchive class, 99 
CFile class, 314 
CStdioFile::ReadString, 570 
read member function 
istream class, 882-883 
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Reading RECT structure (continued) 
archives CRegn::CreateRectRgnIndirect, 544 
object data, 99 CRegn::GetRgnBox, 547 
specified number of bytes, 99 CRgn::RectInRegion, 549 
data in CFile object file buffers, 314 CRegn::SetRectRgn, 549 
object to archive, 473-474 CScrollBar::Create, 553 
text data into buffer from file CStatic::Create, 563 


associated with CStdioFile object, 569-570 CWnd::BeginPaint, 660 
ReadObject member function CWnd::ClientToScreen, 663 
CArchive class, 99—100 CWnd::GetClientRect, 686 
CObject::Serialize, 473 CWnd::GetUpdateRect, 700 
ReadString member function CWnd::GetWindowRect, 703 
CStdioFile class, 569—570 CWnd::InvalidateRect, 707 
RealizePalette member function CWnd::MoveWindow, 714 
CDC class, 224 CWnd::OnNcCalcSize, 762 
CPalette::SetPaletteEntries, 507 CWnd::OnSizeClipboard, 785 
RECT structure, 86 CWnd::ScreenToClient, 802 
-~CButton::Create, 128 CWnd::ScrollWindow, 803 
CComboBox::Create, 143 CWnd::ValidateRect, 820 


CDC::DPtoLP, 175 Rectangle member function 
CDC::DrawFocusRect, 175 CDC class, 224—225 

CDC::DrawText, 177 Rectangles 

CDC::ExtTextOut, 188 bounding 

CDC::FillRect, 189 copying dimensions, 703-704 
CDC::FrameRect, 191 list boxes, retrieving dimensions, 363 
CDC::GetClipBox, 195 of CRgn object, retrieving, 547 
CDC::IntersectClipRect, 212 retrieving dimensions around clipping 
CDC::InvertRect, 213 boundary, 195 

CDC::LPtoDP, 215 calculating width of CRect, 530 
CDC::Pie, 220 checking if within region, 549 
CDC::Rectangle, 225 converting between CRect and LPRECT, 531 
CDC::RectVisible, 225 copies dimensions of scrRect to CRect, 531 
CDC::RoundRect, 227 copying to CRect, 523 

CDC::ScrolIDC, 230 creating 

CDialog::MapDialogRect, 270 CRect object, 524 

CEdit::GetRect, 293 new clipping region, 185 
CEdit::SetRect, 299 NULL, 529 

CEdit::SetRectNP, 300 CRect class described, 521 
CListBox::Create, 356 CWnd, validating client area, 820 
CListBox::GetItemRect, 363 defining upper-left and lower-right corner 
CMenu::TrackPopupMenu, 437 coordinates, 86 


CRect::CopyRect, 523 determining 

CRect::CRect, 524 equality between two, 525 

CRect::EqualRect, 525 equality to CRect, 531 

CRect::IntersectRect, 526 if empty, 527 

CRect::operator &, 535 if top, left, bottom, and right values equal 0, 527 
CRect::operator &=, 533 if within clipping region, 225 

CRect::operator |, 535 inequality, 532 

CRect::operator l=, 533 size, 529 

CRect::UnionRect, 530 whether specified point les within, 528 
CRgn::CreateEllipticR gnIndirect, 541 


Rectangles (continued) 


drawing 
borders, 191 
style indicating focus, 175 
text in, 177-179 
with current pen, 224 
with rounded corners, 226—227 
enclosing update region, retrieving 
coordinates, 700—701 
filling with specified brush, 189-190 
formatting. See Formatting rectangle 
gray, creating for system caret, 672 
height, calculating, 525 
inflating or deflating, 525 
intersecting CRect with rect2 
CRect::operator &, 535 
CRect::operator |, 535 
invalidating client areas within, 707 
inverting contents, 213 
making CRect equal to intersection of two 
rectangles, 526 
making dimensions equal to union of two 
rectangles, 530 
moving bitmaps from source to 
destination, 255-257 
moving 
CRect::OffsetRect, 527 
CRect::operator +=, 532 
CRect::operator —=, 533 
RECT structure, 86 
referencing 
bottom-right point, 523 
top-left point, 529 
regions, creating 
CRegn::CreateRectRgn, 544 
CRegn::SetRectRgn, 549-550 
indirect, 545 


returning new rect equal to CRect plus point 


CRect::operator +, 534 
CRect::operator —, 534 
scrolling, 230 
setting dimensions 


Index 


RectInRegion member function 


CRegn class, 549 


RectVisible member function 


CDC class, 225 


Redrawing 


allowing or preventing changes, 811 
menu bars, 681 


Reduced programming surface area, 10 
Regions 


checking 
equivalent, 546 
if coordinates are within, 548 
if rectangle within CRegn object, 549 
clipping. See Clipping region 
combining, 540 
copying, 540 
creating 
by combination, 539-540 
constructor, 545 
rectangular, 544 
rectangular, indirect, 545 
series of polygonal, 543 
CRen class described, 537 
drawing borders around, 192 
elliptical, creating 
CRgn::CreateEllipticRgn, 541 
CRegn::CreateEllipticR gnIndirect, 541 
filling 
with brush, 218 
with specified brush, 190 
handles, 546 
invalidating client areas within, 708 
moving, 547 
polygonal, creating, 542 
preventing drawing within areas, 186 
rectangular, creating, 549-550 


retrieving bounding rectangle coordinates, 547 


update 
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retrieving coordinates of smallest rectangle that 


encloses, 700-701 
retrieving into specified region, 701 
writing character strings within, 188-189 


CRect::SetRect, 528 
CRect to equal intersection with rect, 533 
equal to union with rect, 533 
multiple-line edit control, 299 

structure, copying client coordinates of CWnd 

client area into, 686—687 
rectDefault data member 
CFrameWnd class, 341 


Registering Windows classes, 12, 37 
ReleaseBuffer member function 

CString class, 588-589 
ReleaseDC member function 

CWnd class, 801—802 

CDC::DeleteDC, 174 

Releasing, device contexts, 801-802 
Remove member function 

CFile class, 315 
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RemoveAll member function Restoring 
CMapStringToOb class, 383 MDI child window, 408 
CObArray class, 458 Windows device context to previous state, 226 
CObList class, 493-494 Retrieving 
RemoveAt member function character line index, 295 
CObArray class, 458-459 Clipboard owner, 687 
CObList class, 494-495 scroll-bar thumb current position, 555 
RemoveHead member function ReverseFind member function 
CObList class, 495 CString class, 589 
RemoveKey member function Right member function 
CMapStringToOb class, 383-384 CString class, 589-590 
RemoveMenu member function RoundRect member function 
CMenu class, 434 CDC class, 226-227 
RemoveTail member function Run member function 
CObList class, 496 CWinApp class, 638 
Removing Run-time 
elements from arrays, 458-459 class structure, returning for specified class, 474 
items from list boxes, 367 returning file pointer associated with stdiobuf 
menu items, 434 object, 916 
pointers from arrays, 458 stream file, CStdioFile class described, 567 
Rename member function structures, getting for CObject-derived class, 470 
CFile class, 315—316 Run-time information 
Renaming files, 315 supplying, 38-39 
ReplaceSel member function supplying dynamic, 40 
CEdit class, 297 RUNTIME_CLASS macro, 474 
Replacing text in edit control, 297 
Repositioning file pointers, 316-317 S 
Reserve areas 
allocating when needed, 923 SaveDC member function 
attaching to stream’s filebuf object, 850 CDC class, 227-228 
attaching to streambuf object, 931 Saving device context current state, 227 
returning pointer to byte after last, 924 sbumpc member function 
returning pointer to, 922 | streambuf class, 929 
returning size in bytes, 922 ScaleViewportExt member function 
setting position values with, 931 CDC class, 228 
setting up, 922 ScaleWindowExt member function 
ResetContent member function CDC class, 229 
CComboBox class, 153 ScreenToClient member function 
CWnd::OnDeletelItem, 729 CWnd class, 802 
CListBox class, 367 Scroll bars 
CWnd::OnDeleteltem, 729 copying 
Resetting edit control undo flag, 290 current minimum and maximum positions, 697 
ResizePalette member function position to specified locations, 556 
CPalette class, 506 creating 
Resizing logical palettes, 506 constructor, 553 
Resources, CResourceException class initializing, 553-555 
described, 536 CScrollBar class described, 551 
RestoreDC member function displaying, 817-818 


CDC class, 226 hiding, 817-818 


Scroll bars (continued) 
horizontal 
called when event occurs in Clipboard 
viewer’s, 742-743 
called when user clicks, 741-742 
in frame windows, 17 
setting position range 
CScrollBar::SetScrollRange, 556-557 
CWnd::SetScrollRange, 812-813 
thumb, retrieving current position, 555 
vertical 
called when clicked, 796—797 
called with event in, 797-798 
Scroll boxes 
retrieving current position, 696—697 
setting to specified position, 811-812 
ScrollLDC member function 
CDC class, 230 
Scrolling 
CWnd, 803-804 
horizontally, called when user clicks on 
bar, 741-742 
list boxes 
retrieving event, 362 
setting width, 370 
text, 296 
ScrollWindow member function 
CWnd class, 803-804 
Searching 
dialog box controls, previous or next 
control, 693-694 
for first matching CObject pointer, 483 
for specified window, 683 
for strings 
list box of combo box, 148, 153 
first character match, 581 
first substring match, 580-581 
window manager’s list for next or previous 
window, 695 
Seconds 
getting, 614 
in current hour, getting, 623 
Seek member function 
CFile class, 316—317 
seekg member function 
istream class, 883 
seekoff member function 
streambuf class, 929-930 
seekp member function 
ostream class, 904 
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seekpos member function 
streambuf class, 930 
SeekToBegin member function 
CFile class, 317 
SeekToEnd member function 
CFile class, 317 
SelectClipRgn member function 
CDC class, 231 
Selecting 
consecutive items in list box, 368 
object into CMetaFileDC, 441 
predefined stock pens, brushes, fonts, 442 
SelectObject member function 
CDC class, 232-233 
CBitmap::CreateBitmap, 110 
CBitmap::CreateBitmapIndirect, 110 


CBitmap::CreateDiscardableBitmap, 112 


CFont::CreateFontIndirect, 334 
CMetaFileDC class, 441-442 

CBitmap::CreateBitmap, 110 

CBitmap::CreateBitmapIndirect, 110 


CBitmap::CreateDiscardableBitmap, 112 


CFont::CreateFontIndirect, 334 
SelectPalette member function 
CDC class, 233-234 
SelectStockObject member function 
CDC class, 234—235 
CDC::SelectStockObject, 235 
CMetaFileDC class, 442 
SelectString member function 
CComboBox class, 153 
CListBox class, 367-368 
SelltemRange member function 
CListBox class, 368 
SendDlgItemMessage member function 
CWnd class, 804 
Sending messages to windows, 805 
SendMessage member function 
CWhnd class, 805 
Serialization 
collection, 23 
DECLARE_SERIAL macro, 39-40 
described, 23 
exceptions 
constructing objects, 105 
specifying cause, 106 
testing objects for eligibility, 473 
Serialize member function 
CObject class, 473 
Services 
CObject class, 23-26 
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Sessions 
called to inform CWnd of end, 736 
called when ending, 776 
SetAbortProc member function 
CDC class, 235—237 
SetActiveWindow member function 
CWnd class, 805—806 
SetAt member function 
CMapStringToOb class, 384-385 
CObArray class, 459-460 
CObList class, 496-497 
CString class, 590 
SetAtGrow member function 
CObArray class, 460-461 
setb member function 
streambuf class, 931 
SetBitmapBits member function 
CBitmap class, 116 
SetBitmapDimension member function 
CBitmap class, 116-117 
SetBkColor member function 
CDC class, 238 
SetBkMode member function 
CDC class, 238-239 
SetBrushOrg member function 
CDC class, 239 
CGdiObject:: UnrealizeObject, 350 
setbuf member function 
fstream class, 843 
ifstream class, 850 
ofstream class, 899 
streambuf class, 931-932 
SetButtonStyle member function 
CButton class, 133 
SetCapture member function 
CWnd class, 806 
SetCaretPos member function 
CWnd class, 806—807 
SetCheck member function 
CButton class, 134 
SetClipboard Viewer member function 
CWnd class, 807 
SetColumnWidth member function 
CListBox class, 369 
SetCurSel member function 
CComboBox class, 154 
CListBox class, 369 
SetDefID member function 
CDialog class, 272 
SetDepth member function 
CDumpContext class, 277 


SetDlgItemInt member function 
CWnd class, 808 
SetDlgItemText member function 
CWnd class, 808 
SetEditSel member function 
CComboBox class, 154—155 
setf member function 
ios class, 863 
SetFocus member function 
CWnd class, 809 
SetFont member function 
CWhnd class, 809 
setg member function 
streambuf class, 932 
SetHandle member function 
CEdit class, 297-298 
SetHorizontalExtent member function 
CListBox class, 370 
SetItemData member function 
CComboBox class, 155 
CListBox class, 370 
SetLength member function 
CFile class, 318 
SetMapMode member function 
CDC class, 240-241 
SetMapperFlags member function 
CDC class, 241 
SetMenu member function 
CWnd class, 810 
SetMenultemBitmaps member function 
CMenu class, 435-436 
setmode member function 
filebuf class, 835 
fstream class, 844 
ifstream class, 851 
ofstream class, 899 
SetModify member function 
CEdit class, 298 
setp member function 
streambuf class, 932—933 
SetPaletteEntries member function 
CPalette class, 506—507 
SetParent member function 
CWnd class, 810 
SetPasswordChar member function 
CEdit class, 299 
SetPixel member function 
CDC class, 242 
SetPolyFillMode member function 
CDC class, 242—243 


SetRect member function 
CEdit class, 299-300 
CRect class, 528—529 
SetRectEmpty member function 
CRect class, 529 
SetRectNP member function 
CEdit class, 300 
SetRectRgn member function 
CRegn class, 549-550 
SetRedraw member function 
CWnd class, 811 
SetROP2 member function 
CDC class, 243-244 
SetScrollPos member function 
CScrollBar class, 556—557 
CWnd class, 811-812 
SetScrollRange member function 
CScrollBar class, 557 
CWnd class, 812-813 
SetSel member function 
CEdit class, 301 
CListBox class, 371 
SetSize member function 
CObaArray class, 461 
SetState member function 
CButton class, 134 
SetStatus member function 
CFile class, 318-319 
SetStretchBltMode member function 
CDC class, 245 
SetSysModalWindow member function 
CWnd class, 813 
SetTabStops member function 
CEdit class, 301—302 
CListBox class, 371—372 
SetTextAlign member function 
CDC class, 246-247 
SetTextCharacterExtra member function 
CDC class, 247 
SetTextColor member function 
CDC class, 248 
SetTextJustification member function 
CDC class, 248—249 
SetTimer member function 
CWnd class, 813-814 
Setting 
background mode, 238 
binary/text mode 
filebuf objects, 835 
stream’s filebuf object, 844, 851 
streams, 868, 899 
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bitmap bits to values, 116 
bitmap-stretching mode, 245 
characters’ range in edit control, 301 
colors 

background, current, 238 

text, 248 
CWnd control caption or text, 808 


device contexts, x- and y-extents for associated 


windows, 252 

drawing mode, 243-244 

dump depth, 276-277 

error-bits, 856 

files’ status, 318 

fonts, CWnd, 809 

format flags in streams, 870 

formatting rectangle of multiple-line edit 

control, 299-300 

intercharacter spacing, 247 

mapping mode, 240-241 

menus, current to specified, 810 

passwords, 299 

pixels at specified point, 242 

polygon-filling mode, 242 

scroll bar position range 
CScrollBar::SetScrollRange, 557 
CWnd::SetScrollRange, 812-813 

scroll-bar thumb position, 556 

streambuf object’s buffering state, 937 

stream’s 
fill character, 869 
format conversion base to 10, 868 
format conversion base to 16, 868 
format conversion base to 8, 869 
internal field width parameter, 871 
internal field width variable, 865 
internal flags, 858-859 
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internal floating-point precision variable, 870 


system timer, 813-814 
windows 
size, position, ordering, 814-816 


SetTopIndex member function 


CListBox class, 372 


Set ViewportExt member function 


CDC class, 250 


SetViewportOrg member function 


CDC class, 251 


SetWindowExt member function 


CDC class, 252 


SetWindowOrg member function 


CDC class, 253 
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SetWindowPos member function 
CWnd class, 814-816 
SetWindowText member function 
CWhnd class, 816 
CEdit::ReplaceSel, 297 
sgetc member function 
streambuf class, 933 
sgetn member function 
streambuf class, 933 
ShowCaret member function 
CWnd class, 816-817 
ShowDropDown member function 
CComboBox class, 155 
Showing, list box of combo box, 155 
ShowOwnedPopups member function 
CWnd class, 817 
ShowScrollBar member function 
CWnd class, 817-818 
Show Window member function 
CWnd class, 818-819 
CWinApp::m_nCmdShow, 640 
Size 
adding to CSize, 560 
arrays 
establishing, 461 
returning, 456 
checking 
equality between sizes, 560 
inequality between sizes, 560 
creating CSize object, 559 
CSize class described, 558 
returning difference between two sizes, 561 
returning sum of two sizes, 561 
subtracting, 561 
Size member function 
CRect class, 529 
Snapshots, memory, taking, 54 
snextc member function 
streambuf class, 934 
Spacing, intercharacter, retrieving setting, 206 
SpanExcluding member function 
CString class, 591 
SpanIncluding member function 
CString class, 591 
Special-purpose words table, indexing 
10s::1word, 860 
10s::pword, 861 
sputbackc member function 
streambuf class, 934 — 
sputc member function 
streambuf class, 934—935 


sputn member function 
streambuf class, 935 
StartDoc member function 
CDC class, 254 
StartPage member function 
CDC class, 254 
Static control 
creating 
attaching, 563-564 
constructor, 563 
CStatic class described, 562 
Status 
files 
getting, 310-311 
setting, 318 
menu items, specifying, 425-426 
stdio member function 
10S class 
10S::sync_with_stdio, 863 
ostream::osfx, 902 
stdiobuf class 
described, 915 
member functions 
stdiobuf, 916 
~stdiobuf, 916 
stdiofile, 916 
stdiobuf constructor, 916 
stdiobuf destructor, 916 
stdiobuf objects 
creating, 916 
destroying, 916 
returning C run-time file pointer, 916 
returning pointers to, 918 
stdiofile member function 
stdiobuf class, 916 
stdiostream class 
described, 917 
member functions 
rdbuf, 918 
stdiostream, 918 
~stdiostream, 918 
stdiostream constructor, 918 
stdiostream destructor, 918 
stdiostream objects 
creating, 918 
destroying, 918 
Stock objects, retrieving handle to, 345-346 
Storing 
archives 
object or primitive type, 103 
specified object to, 101 


stossc member function 
streambuf class, 935 
str member function 
istrstream class, 892 
ostrstream class, 914 
strstream class, 940 
strstreambuf class, 944 
Stream objects, predefined 
cerr, 900 
cin, 875 
clog, 900 
cout, 900 
streambuf class 
consume defined, 927 
defining characteristics of derived class 
streambuf::overflow, 926 
streambuf::sync, 937 
streambuf::underflow, 938 
described, 919-921 
get area 
returning lower bound, 924 
returning number of characters available for 
fetching, 926 
returning pointer to byte after last, 925 
setting pointer values, 932 
get pointers 
following fetched characters, 933 
incrementing, 925 
moving back, 934 
moving forward one character, 934, 935 
returning character at, 933 
returning to next character to be fetched, 925 
testing, 934 
member functions 
allocate, 922 
base, 922 
blen, 922 
dbp, 923 
doallocate, 923 
eback, 924 
ebuf, 924 
egptr, 924 
epptr, 925 
gbump, 925 
gptr, 925 
in_avail, 926 
out_waiting, 926 
overflow, 926-927 
pbackfail, 927 
pbase, 928 
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member functions (continued) 
pbump, 928 
pptr, 928 
sbumpc, 929 
seekoff, 929-930 
seekpos, 930 
setb, 931 
setbuf, 931-932 
setp, 932-933 
sgetc, 933 
sgetn, 933 
snextc, 934 
sputbackc, 934 
sputc, 934-935 
sputn, 935 
Stossc, 935 
streambuf, 936 
~streambuf, 936 
sync, 884, 907, 937 
unbuffered, 937 
underflow, 938 
put area 
returning first byte of, 928 
returning pointer to start of, 928 
setting pointer values, 932 
storing character, 934 
put pointer 
following stored characters, 935 
incrementing, 928 
repositioning external file pointer, 927 
attaching to object, 931 
reserve area 
returning pointer to byte after last, 924 
returning pointer to, 922 
returning size in bytes, 922 
setting position values, 931 
setting up, 922 


returning current character and advancing get 


pointer, 929 


returning number of characters available for 


fetching, 926 
returning pointer to byte after last, 924 
virtual overflow function, 926-927 
virtual sync function, 937 
virtual underflow function, 938 
writing ASCII debugging information on 
stdout, 923 


streambuf constructor, 936 
streambuf destructor, 936 
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streambuf objects 


Index 


associated with stream, returning pointer to, 862 
changing position for, 929-930 

changing position relative to stream beginning, 930 
creating, 936 

reserve area, allocating when needed, 923 

setting buffering state, 937 

virtual destructor, 936 


Streams 


assigning istream object to istream_withassign 
object, 889 
attaching 
to already open file, 894 
to specified open file, 846 
buffer-deletion flag, assigning value to, 856 
buffers 
flushing, 902 
returning number of bytes stored in, 913 
returning pointer to strstreambuf buffer object, 913 
C++, synchronizing with standard C stdio 
streams, 863 
changing, position value, 904 
characters 
inserting into output, 903 
returning next without extracting, 882 
returning number extracted by last unformatted 
input function, 877 
synchronizing internal buffer with external 
character source, 884 
clearing format flags, 864 
determining if error bits are set, 866 
diagnostic output, human-readable text, 273 
errors 
determining if error bits are clear, 859 
determining if error bits are set, 866 
returning current specified error state, 862 
extracting 
characters and discarding, 880 
data, 878, 880 
white space, 877, 886 
extraction operations 
called after, 881 
called prior to, 880 
operators, 885 
specified number of bytes, 883 
file descriptor, returning, 895 
filebuf class described, 831 


Streams (continued) 


filebuf objects 


attaching specified reserve area, 843, 850, 899 


closing, 894 
opening file and attaching, 842 
opening file for attachment, 898 
returning pointer to associated, 898 
returning pointer to, 850 
setting binary/text mode, 899 
flushing output buffer, 907 
fstream class described, 836 
get pointers 
changing, 883 
getting value, 884 
getting position value, 904 
ifstream class described, 845 


- input, putting character back into, 882 


insert operations 
called after, 902 
called before, 902 
inserting 
arguments into, 906 
bytes, 905 
newline character and flushing buffer, 907 
null-terminator character, 907 
internal flags variable, setting, 858-859 
10s class described, 852 
iostream class described, 872 
Iostream_init class described, 874 
istream class described, 875 
istream objects 
creating, 881 
destroying, 882 
istream_withassign class described, 887 
istrstream class described, 890 
masks 
current radix flag bits, 867 
floating-point format flag bits, 867 
object state variables, providing without class 
derivation, 865 
ofstream class described, 893 
opening file and attaching to filebuf object, 849 
ostream class described, 900 
ostream_withassign class described, 908 
ostrstream class described, 911 
padding flag bits, obtaining, 867 
returning associated file descriptor 
fstream::fd, 839 
ifstream::fd, 847 


Streams (continued) 
returning pointer to associated filebuf buffer 
object, 843 

setting 
binary/text mode, 851 
fill character, 869 
floating-point precision variable, 861 
format conversion base to 8, 869 
format conversion base to 10, 868 
format conversion base to 16, 868 
internal field width parameter, 871 
internal field width variable, 865 
internal fill character variable, 857 
internal floating-point precision variable, 870 
mode to text, 871 
specified format bits, 863 
text to binary mode, 868 

special-purpose words table, indexing 
10s::iword, 860 
ios::pword, 861 

stdiobuf class described, 915 

Sstdiostr class described, 917 

streambuf class described, 919 

streambuf objects, returning pointer to, 862 

strstream class described, 939 


strstreambuf buffer object, returning pointer to, 892 


strstreambuf class described, 943 
synchronizing internal buffer with external 
character source, 884 
testing 
end-of-file, 857 
for attachment to open file, 849 
for attachment to specified open disk file, 842 
for attachment to specified open file, 895 
for serious I/O errors, 855 
tying to ostream, 864 
virtual overflow function, 926—927 
StretchBlt member function 
CDC class, 255—257 
Strings 
adding 
list boxes, 355 
to list boxes, 366 
character 
to list box of combo box, 142 
retrieving width, height, 204-205 
comparing two 
CString::Collate, 576 
CString::Compare, 577 
CString::CompareNoCase, 577-578 
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converting 
characters from ANSI to OEM character set, 576 
characters from OEM to ANSI character set, 588 
CString object to lowercase, 586 
CString object to uppercase, 587 
corresponding to CTimeSpan, generating, 621 
CString class described, 572 
CTime object, corresponding to 
converted, 609 
unconverted, 610 
deleting 
from list boxes, 359 
from list box in combo box, 147 
extracting first characters from CString object and 
returning copy, 585 
extracting from CString object the largest substring 
excluding specified characters, 591 
extracting last characters from CString object and 
returning copy, 589-590 
extracting substring of specified length and 
returning copy, 587 
finding in list boxes, 361 
getting from list box of combo box, 150 
inserting list box of combo box, 151 
justifying, 248-249 
list boxes 
getting length, 366 
getting, 365 
scrolling selected, 369 
searching for matching, 367 
selecting, 371 
lists of objects, CStringList class described, 603 
making CString object an empty string, 580 
menu items, copying, 427 
objects arrays, CStringArray class described, 601 
overwriting specified character, 590 
reading specified Windows string resource, 586 
returning 
character specified by index, 581 
count of characters in CString object, 584 
pointer to internal character buffer and matching 
length, 583-584 
pointer to internal character buffer for CString 
object, 582-583 
reversing character order in CString object, 586 
searching 
CString object for last substring match, 589 
for in list box of combo box, 148, 153 
first character match, 581 
first substring match, 580-58 1 
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Strings (continued) 
setting to specified integer value, 808 
streams, returning pointer to character array, 892 
terminating use of buffer, 588 
testing CString object for empty condition, 584 
writing 
at specified location, 259 
tabbed text, 258-259 
to regions, 188-189 
strstream buffer objects, returning pointer to, 892 
strstream class 
buffer, returning number of bytes in, 940 
described, 939 
member functions 
pcount, 940 
rdbuf, 940 
str, 940 
strstream, 941] 
~strstream, 942 
returning 
number of bytes in buffer, 940 
pointer to internal character array, 940 
pointer to strstreambuf object, 940 
strstream constructor, 941 
strstream destructor, 942 
strstream objects 
creating, 941 
destroying, 942 
returning pointer to, 940 
strstreambuf class 
described, 943 
member functions 
freeze, 913, 944 
str, 944 
strstreambuf, 945-946 
~strstreambuf, 946 
preventing automatic memory deletion, 944 
returning pointer to internal character array, 944 
strstreambuf constructor, 945-946 
strstreambuf objects 
creating, 945 
destroying, 946 
returning pointer 
from associated stream, 913 
to internal character array, 944 
Structures 
COMPAREITEMSTRUCT, 77-78 
CREATESTRUCT, 78-79 
DELETEITEMSTRUCT, 80 
DRAWITEMSTRUCT, 81-83 


Structures (continued) 
MEASUREITEMSTRUCT, 83-84 
PAINTSTRUCT, 84-85 
POINT, 85 
RECT, 86 

Styles, button 

changing, 133 
getting, 131 
windows, retrieving, 698 

Subscript operators 
CObArray::operator[], 462 
CString class, 597 

Subtracting 
rectangles, 533-534 
sizes, 561 
time spans 

CTimeSpan::operator +,—, 625 
CTimeSpan::operator +=,—=, 626 

sync member function 
istream class, 884 
streambuf class, 937 
used by ostream flush operator, 907 

Synchronizing C++ streams with standard C stdio 

streams, 863 

sync_with_stdio member function 
10S Class, 863 

System time, called after change, 794 


T 


Tab stops 
setting in edit control, 301 
setting in list boxes, 371 
TabbedTextOut member function 
CDC class, 258-259 
tellg member function 
istream class, 884 
tellp member function 
ostream class, 904—905 
Terminating 
default function, 61 
dialog boxes, modal, 267 
linking to specified function, 61 
on fatal errrors, 62 
Testing 
objects for class derivation, 472 
validity of object’s internal state, 53 
Text 
alignment flags, retrieving status, 205 
caption titles, returning length, 704 


Text (continued) 
colors 
retrieving current, 207 
setting, 248 
computing line dimensions, 207 
CWnd, setting, 808 
dialog boxes, retrieving, 691 
drawing dimmed, 210-212 
formatted, drawing in rectangle, 177, 179 
getting from list boxes, 365 
lines, retrieving number of, 292 
replacing current selection in edit control, 297 
scrolling in multiple-line edit control, 296 
setting 
alignment flags,246—247 
caption title to specified, 816 
justification, 248-249 
to specified integer value, 808 
specifying length in an edit control, 294 
streams, setting mode to, 871 
window captions, copying into specified buffer, 704 
writing string at specified location, 
CDC::TabbedTextOut, 258-259 
CDC::TextOut, 259 
TextOut member function 
CDC class, 259-260 
32-bit values, setting, combo-box item, 155 
THROW macro, 66 
ThrowErrno data member 
CFileException class, 325-326 
THROW_LAST macro, 67 
ThrowOsError data member 
CFileException class, 326 
tie member function 
10s class, 864 
Time 
absolute, representing, 615 
adding and subtracting CTimeSpan object, 616 
comparing absolute, CTime comparison 
operators, 616 
creating CTime object, 608-609 
CTime class described, 606 
current, 610 
day 
of month, 611 
of week, 611 
diagnostic dumping and storing to archive, 617 
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Time (continued) 
generated formatted string 
converted, 609 
unconverted, 610 
getting struct tm with local time 
decomposition, 612 
getting struct tm with UCT decomposition, 611 
getting time_t value for CTime object, 614 
hours, getting, 613 
minutes, getting, 613 
months, getting, 613 
seconds, getting, 614 
source, copying into CTime object, 615 
span 
adding and subtracting, 625 
comparing two relative time values, CTimeSpan 
comparison operators, 626 
copying source object, 625 
creating CTimeSpan object, 620-621 
CTimeSpan class described, 618 
days, getting, 622 
diagnostic dumping and storing to archive, 627 
generating formatted string corresponding to 
CTimeSpan, 621 
hours 1n current day, 622 
hours, total, 623 
minutes in current hour, 623 
minutes, total, 624 
seconds in current minute, 623 
seconds, total, 624 
system, called after change, 794 
years, getting, 614 
Timers 
called at specified intervals, 795 
killing specified event, 711 
system, installing, 813-814 
TopLeft member function 
CRect class, 529 
TRACE macro, 56 
TrackPopupMenu member function 
CMenu class, 436 
Translating 
CWinApp messages before dispatched to 
DispatchMessage function, 801 
text of specified dialog box control into 
integer, 690-69 1 
TranslatorAccelerator Windows function, 787 
TRY macro, 67 
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unbuffered member function 
streambuf class, 937 
underflow member function 
streambuf class, 938 
Undo flags 
clearing, resetting, 290 
returning edit operations status, 285 
Undo member function 
CEdit class, 302 
Undoing, last operation in edit control, 302 
Union operator 
CRect class, 531, 535 
UnionRect member function 
CRect class, 530 
Unlocking, range of bytes in file, 319 
UnlockRange member function 
CFile class, 319 
UnrealizeObject member function 
CBrush class 
CWnd::OnEraseBkgnd, 738 
CGdiObject class, 350 
unsetf member function 
10S Class, 864 
Update region 
retrieving coordinates of smallest rectangle that 
encloses, 700-701 
retrieving into specified region, 701 
UpdateColors member function 
CDC class, 260 
UpdateWindow member function 
CWnd class, 819 
Updating, client areas, 819 


V 


ValidateRect member function 
CWnd class, 820 
ValidateRgn member function 
CWnd class, 820 
Validating client area 
within given rectangle, 820 
within given region, 820 
Validity checking of objects, 466 
Variables 
floating-point precision, setting, 861 
internal field width, setting, 865 
internal fill character, setting, 857 
object state, providing without class derivation, 865 


VERIFY macro, 57 
Viewports 
modifying extents, 228 
modifying origin, 217 
retrieving device contexts’ extents, 209 
retrieving origin coordinates associated with device 
context, 209 
setting 
origin of device context, 251 
x- and y-extents, 250 
Virtual sync function 
streambuf class 
streambuf::sync, 937 
Virtual underflow function 
streambuf class, streambuf::underflow, 938 
Void pointers 
16-bit words keyed by, 375 
arrays, CPtrArray class described, 517 
CPtrList class described, 519 
keyed to void pointers, 373 
maps keyed by 16-bit words, 393 
maps keyed by CString objects, 387 
void* () operator 
10S class, 866 


W 


Weeks, getting days of, 611 
WHITERECT structure 
CStatic::Create, 566 
Width 
internal field variable, setting, 865 
streams, setting internal field parameter, setw, 871 
Width member function 
CRect class, 530 
10S class, 865 
WIN.INI, called after change made, 798—799 
Window classes (list), 6 
WindowFromPoint member function 
CWnd class, 821 
WindowProc member function 
CWnd class, 821 
Windows 
activating or deactivating, 715 
active CWnd object, returning pointer to, 685 
applications. See Windows applications 
base class (list), 6 
bitmaps, loading, 115-116 
C++ language features, 8 
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called when 
activating for different task, 716 
Clipboard contents emptied, 731 
device-mode settings changed, 731 
caption titles, copying into specified buffer, 704 
returning length, 704 
carets, getting current position, 686 
changing 
position and dimensions, 714-715 
size, position, ordering, 814-816 
classes 
categories, 1 1—20 
described, 5 
registering, 12, 37 
Clipboard 
called for each window in viewer chain when 
contents change, 731—732 
viewer, getting first window in, 687 
closing, signaling confirmation, 720 
CMenu class described, 19 
colors, called when change made, 788 
containing given point, identifying, 821 
controls, 16 
creating, containing application-supplied 
message, 711-714 
CWnd 
displaying, 818-819 
making active, 805-806 
retrieving current font, 692 
default procedure, calling 
CWnd::Default, 673 
CWnd::DefWindowProc, 674 
defining parameters for initialization, 78—79 
dialog classes (list), 6 
display context, retrieving, 703 
displaying, 818-819 
edit control. See Windows edit control 
enabling for mouse and keyboard input, 710 
flashing once, 683-684 
fonts, called when changing, 738-739 
frame 
See also Frame windows 
CFrameWnd class described, 336 
classes (list), 6 
GDI objects 
See also GDI objects 
attaching, 344 
CGdiObject class described, 342 
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Windows (continued) 
GDI objects (continued) 
deleting from memory, 346 
detaching, 347 
retrieving handle to, 345-346 
global functions described, 7 
handles 
detaching from CWnd object, 676 
getting, CWnd object, 676 
hiding, called when, 783-784 
iconic, specifying, 710 
initialization file, called after change 
made, 798-799 
input control, 739-740 
macros described, 7 
making CWnd into system-modal, 813 
manager’s list, searching for next or previous 
window, 695 
MDI 
activating different child window, 405 
creating client window, 404 
memory compacting specification, 722 
menus 
returning pointer to CWnd’s, 693 
specifying handle to, 419 
message processing, 12 
message-based environment, 8 
messages 
calling default procedure 
CWnd::Default, 673 
CWnd::DefWindowProc, 673 
direct calls, 16 
noncontrol, 14 
sending, 805 
minimized, called if about to be dragged, 775 
minimizing, 664 
modifying extents, 229 
nonclient area, called when needing change to 
indicate active or inactive state, 761 
notification messages, 13-14 
open, called when user requests, 777 
origin 
modifying, 217 
retrieving coordinates, 210 
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overlapping, bringing CWnd to top of stack, 661 


owner-draw control, creating, 666 
overlapping 
informing of dimensions, 83-84 
painting information, 81—83 
painting, marking end, 682 
palettes, called after changed, 773-774 
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Windows (continued) 


pop-up 
changing size, position, ordering, 814, 816 
creating with extended style, 666—670 
determining most recently active, 692-693 
procedure, providing, 821 
removing from Clipboard viewer chain, 717-718 
restoring minimized to original size and 
position, 800 
retrieving 
coordinates associated with device context, 209 
pointer to CWnd with input focus, 692 
scrolling, 803-804 
searching 
for name-specified, 683 
for next or previous on manager’s list, 695 
window manager’s list for, 702 
setting 
caption title to specified text, 816 
origin of device context, 253 
x- and y-extents, 252 
static control, 562 
style, returning, 698 
subclassed, original WndProc address, 698 
system-modal, returning, 698 
validating client area, 820 
visibility, determining, 710 


Windows applications 


accessing command-line arguments entered at 
start, 639 
cleaning up at termination, 631 
constructor, 631 
CWinApp class described, 628 
handle 
to current instance, 639 
to previous instance, 639 
icon resource, 
loading specified, 633 
loading predefined, 634, 636 
idle-time processing, 637 
instance initializing, 632 
loading cursor resources 
CWinApp::LoadCursor, 633 
CWinApp::LoadOEMCursor, 634 
CWinApp::LoadStandardCursor, 635 
making main window visible, 640 
messages 
creating and displaying, 711-714 
filtering, 638 


Windows applications (continued) 
messages (continued) 
last retrieved, 639 
providing default loop, 638 
name, 640 
one-time initializing, 632 
overridable member functions, 11 
storing pointer to main window object, 640 
Windows edit control 
creating and attaching to CEdit object, 286-289 
creating, CEdit class, 282 
current selection 
clearing, 285 
copying, 286 
cutting, deleting, 289 
described, 282 
undo flags, resetting, 290 
Windows windows 
attaching, to CWnd object, 659 
called to know maximized position of 
dimensions, 740-741 
desktop, returning, 689 
destroying, 675 
Windows, child 
accessing overridable member functions 
CFrameWnd::GetChildFrame, 339 
CFrameWnd::GetParentFrame, 340 
activating, next child, 407 
active MDI, returning, 405 
arranging 
in tiled format, 409 
minimized, 659 
buttons as, 16 
called on activation or deactivation, 753-754 
called on creation or destruction, 774—775 
called when about to be drawn, 726-727 
called when changing size or position, 720 
changing 
parent, 810 
size, position, ordering, 814-816 
classes (list), 6 
creating 
and attaching, 397 
attaching to CWnd object, 664-665 
constructor, 397 
CWnd, returning ID, 689 
determining which contains specified 
point, 662—663 
handling activation message, 398 
identifying, 709 


Windows, child (continued) 
MDI 
activating, 405 
arranging in cascade, 406 
client, handle for, 410 
destroying, 399 
maximizing, 399, 407 
restoring, 399 
returning current, 406 
returning parent MDI frame, 398 
minimized, arranging, 406 
restoring, 408 
searching for top-level, 700 
Windows, frame 
creating, 403 
replacing menu of MDI, 408—409 
Windows, parent, retrieving, 696 
Windows, pop-up, associated with CWnd object, 
showing or hiding, 817 
WM_CHANGECBCHAIN message 
CWnd::OnChangeCbChain message handler, 718 
CWnd::SetClipboard Viewer, 807 
WM_CHAR message 
CWnd::OnCharToltem message handler, 719 
CWnd::OnGetDlgCode message handler, 739 
WM_CHARTOITEM message 
CListBox::Create, 359 
WM_CHILDACTIVATE message 
CWnd::OnChildActivate message handler, 720 | 
WM_COMMAND message 
CButton::Create, 130 
CWnd::OnCommand message handler, 721 
CWnd::OnSysCommand message handler, 790 
WM_COMPAREITEM message 
CWnd::OnCompareltem message handler, 722 
WM_CREATE message 
CButton::Create, 128 
CComboBox::Create, 144 
CEdit::Create, 286 
CListBox::Create, 356 
CWnd::CreateEx, 667 
CWnd::OnNcCreate message handler, 762 
WM_CTLCOLOR message 
CStatic::Create, 565 
CWnd::OnCtlColor message handler, 727 
WM_DESTROY message 
CWnd::Destroy Window, 675 
CWnd::SetClipboard Viewer, 807 
WM_DESTROYCLIPBOARD message 
CWnd::OnDestroyClipboard message handler, 731 
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WM_DEVMODECHANGE message 
CWnd::OnDevModeChange message handler, 731 
WM_DRAWCLIPBOARD message 
CWnd::OnDrawClipboard message handler, 732 
CWnd::SetClipboard Viewer, 807 
WM_DRAWITEM message 
CButton::Create, 130 
CMenu::AppendMenu, 417 
WM_ENABLE message 
CWnd::EnableWindow, 681 
WM_ENDSESSION message 
CWnd::OnQueryEndSession message handler, 776 
WM_ENTERIDLE message 
CWnd::CreateEx, 668 
WM_ERASEBKGND message 
CWnd::GetUpdateRect, 700 
CWnd::OnEraseBkgnd message handler, 738 
CWnd::OnliconEraseBkgnd message handler, 743 
WM_FONTCHANGE message 
CWnd::OnFontChange message handler, 738 
WM_GETDLGCODE message 
CDialog::IsDialogMessage, 269 
CWnd::OnGetDlgCode message handler, 739 
WM_GETMINMAXINFO message 
CButton::Create, 128 
CComboBox::Create, 144 
CEdit::Create, 286 
CListBox::Create, 356 
CWnd::CreateEx, 667 
WM_GETTEXT message 
CEdit::FmtLines, 290 
CWnd::GetDlgItemInt, 690 
WM_INITDIALOG message 
CDialog::Create, 265 
CDialog::CreateIndirect, 266 
CDialog::OnInitDialog message handler, 271 
CWnd::OnMeasureltem message handler, 755 
WM_INITMENU message 
CWnd::GetSystemMenu, 699 
WM_KEYDOWN message 
CWnd::OnSysKeyUp message handler, 794 
CWnd::OnV KeyToltem message handler, 795 
WM_KEYUP message 
CWnd::OnSysKeyUp message handler, 794 
WM_KILLFOCUS message 
CWnd::SetFocus, 809 
WM_LBUTTONDBLCLK message 
CWnd::OnLButtonDbIClk message handler, 748 
WM_LBUTTONDOWN message 
CWnd::OnLButtonDbIClk message handler, 748 
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WM_MBUTTONDBLCLK message 

CWnd::OnMButtonDbIClk message handler, 751 
WM_MBUTTONDOWN message 

CWnd::OnMButtonDbIClk message handler, 751 
WM_MDIACTIVATE message 

CMDIFrameWnd::MDtIActivate, 405 
WM_MEASUREITEM message 

CButton::Create, 130 

CMenu::AppendMenu, 417 
WM_MENUCHAR message 

CWnd::OnMenuChar message handler, 757 
WM_MOUSEACTIVATE message 

CWnd::OnMouseActivate message handler, 759 
WM_MOUSEMOVE message 

CWnd::OnMouseMove message handler, 760 
WM_NCACTIVATE message 

CMDIFrameWnd::MDIActivate, 405 

CWnd::OnMDIActivate message handler, 754 

CWnd::OnNcActivate message handler, 761 
WM_NCCALCSIZE message 

CButton::Create, 128 

CComboBox::Create, 144 

CEdit::Create, 286 

CListBox::Create, 356 

CWnd::CreateEx, 667 
WM_NCCREATE message 

CButton::Create, 128 

CComboBox::Create, 144 

CEdit::Create, 286 

CListBox::Create, 356 

CWnd::CreateEx, 667 

CWnd::OnNcCreate message handler, 762 
WM_NCDESTROY message 

CWnd::Destroy Window, 675 

CWnd::OnNcDestroy message handler, 763 
WM_NCHITTEST message 

CWnd::OnNcHitTest message handler, 764 
WM_ONERASEBKGND message 

CWnd::BeginPaint, 660 
WM_OTHERWINDOWDESTROYED message 

CWnd::Destroy Window, 675 
WM_PAINT message | 

CWnd::BeginPaint, 660 

CWnd::OnPaint message handler, 772 

CWnd::ScrollWindow, 803 

CWnd:: ValidateRect, 820 
WM_PARENTNOTIFY message 

CWnd::Destroy Window, 675 
WM_QUERYDRAGICON message 

CWnd::OnQueryDragIcon message handler, 775 


WM_QUERYENDSESSION message 
CWnd::OnQueryEndSession message handler, 776 
WM_QUERYNEWPALETTE message 
CWnd::OnQueryNewPalette message handler, 777 
WM_QUERYOPEN message 
CWnd::OnQueryOpen message handler, 777 
WM_QUIT message 
CFrameWnd::~CFrameWnd, 338 
CWinApp::Run, 638 
WM_RBUTTONDBLCLK message 
CWnd::OnRButtonDbIClk message handler, 778 
WM_RBUTTONDOWN message 
CWnd::OnRButtonDbIClk message handler, 778 
WM_SETCURSOR message 
CWnd::OnSetCursor message handler, 782 
WM_SETFOCUS message 
CWnd::SetFocus, 809 
WM_SETFONT message 
CDialog::Create, 265 
CDialog::CreateIndirect, 266 
CDialog::OnSetFont message handler, 271 
WM_SETREDRAW message 
CListBox::Create, 358 
WM_SYSCHAR message 
CWnd::SetFocus, 809 
WM_SYSCOMMAND message 
CWnd::GetSystemMenu, 699 
CWnd::OnCommand message handler, 721 
CWnd::OnNcLButtonDbIClk message handler, 765 
CWnd::OnNcLButtonDown message handler, 765 
CWnd::OnNcLButtonUp message handler, 766 
CWnd::OnNcMouseMove message handler, 769 
CWnd::OnSysCommand message handler, 789 
WM_SYSKEYDOWN message 
CWnd::OnSysChar message handler, 787 
CWnd::OnSysKeyDown message handler, 792 
CWnd::SetFocus, 809 
WM_SYSKEYUP message 
CWnd::OnSysChar message handler, 787 
CWnd::OnSysKeyDown message handler, 792 
CWnd::OnSysKeyUp message handler, 793 
CWnd::SetFocus, 809 
WM_TIMECHANGE message 
CWnd::OnTimeChange message handler, 794 
WM_TIMER message 
CWnd::KillTimer, 711 
CWnd::SetTimer, 814 
WM_VKEYTOITEM message 
CListBox::Create, 359 
CWnd::OnV KeyToltem message handler, 795 
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WM_WININICHANGE message 
CWnd::OnWinIniChange message handler, 798 
wndBottom static data member 
CWnd class, 822 
wndTop static data member 
CWnd class, 822 
Words 
16-bit, CWordArray class described, 823 
Write member function 
CArchive class, 100 
CFile class, 320 
CStdioFile::WriteString, 570 
write member function 
ostream class, 905 
WriteObject member function 
CArchive class, 101 
CObject::Serialize, 473 
WriteString member function 
CStdioFile class, 570 
Writing 
bytes to streams, 905 
character strings to regions, 188—189 
data from buffer 
to CFile object-associated file, 320 
to file associated with CStdioFile object, 570 
object to archive , 473-474 
to archives, 100 
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xalloc member function 
10s class, 865 


Y 


Years, getting, 614 


Microsoft Corporation 
One Microsoft Way 
Redmond, WA 98052-6399 


Micresoft: 


~ 1191 Part No. 24776 


